/ Hex Artifact Content
Login

Artifact 09a5256ee80dfc7cb4353739f78e4267be323574:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 32 33 39 20 32 30 30 37 2f  in,v 1.239 2007/
05f0: 30 38 2f 32 34 20 30 33 3a 35 31 3a 33 34 20 64  08/24 03:51:34 d
0600: 72 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e  rh Exp $.*/.#ifn
0610: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  def _SQLITE3_H_.
0620: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33  #define _SQLITE3
0630: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  _H_.#include <st
0640: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
0650: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
0660: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
0670: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
0680: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
0690: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
06a0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64  rom C++..*/.#ifd
06b0: 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65  ef __cplusplus.e
06c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
06d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
06e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
06f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
0700: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
0710: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
0720: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
0730: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f  extern.#endif../
0740: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 74  *.** Make sure t
0750: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 68 65  hese symbols whe
0760: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
0770: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
0780: 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 2e 0a  header.** file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a  ersion Numbers.*
0840: 2a 0a 2a 2a 20 54 68 65 20 76 65 72 73 69 6f 6e  *.** The version
0850: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
0860: 69 62 72 61 72 79 20 69 73 20 63 6f 6e 74 61 69  ibrary is contai
0870: 6e 65 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  ned in the sqlit
0880: 65 33 2e 68 0a 2a 2a 20 68 65 61 64 65 72 20 66  e3.h.** header f
0890: 69 6c 65 20 69 6e 20 61 20 23 64 65 66 69 6e 65  ile in a #define
08a0: 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 56 45   named SQLITE_VE
08b0: 52 53 49 4f 4e 2e 20 20 54 68 65 20 53 51 4c 49  RSION.  The SQLI
08c0: 54 45 5f 56 45 52 53 49 4f 4e 0a 2a 2a 20 6d 61  TE_VERSION.** ma
08d0: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
08e0: 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  a string constan
08f0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 72  t..**.** The for
0900: 6d 61 74 20 6f 66 20 74 68 65 20 76 65 72 73 69  mat of the versi
0910: 6f 6e 20 73 74 72 69 6e 67 20 69 73 20 22 58 2e  on string is "X.
0920: 59 2e 5a 22 2c 20 77 68 65 72 65 0a 2a 2a 20 58  Y.Z", where.** X
0930: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0940: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 2c 20 59 20  rsion number, Y 
0950: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
0960: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20  sion number and 
0970: 5a 0a 2a 2a 20 69 73 20 74 68 65 20 72 65 6c 65  Z.** is the rele
0980: 61 73 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ase number.  The
0990: 20 58 2e 59 2e 5a 20 6d 69 67 68 74 20 62 65 20   X.Y.Z might be 
09a0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 22 61 6c 70  followed by "alp
09b0: 68 61 22 20 6f 72 20 22 62 65 74 61 22 2e 0a 2a  ha" or "beta"..*
09c0: 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 20 22 33  * For example "3
09d0: 2e 31 2e 31 62 65 74 61 22 2e 0a 2a 2a 0a 2a 2a  .1.1beta"..**.**
09e0: 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73 20   The X value is 
09f0: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69  always 3 in SQLi
0a00: 74 65 2e 20 20 54 68 65 20 58 20 76 61 6c 75 65  te.  The X value
0a10: 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68   only changes wh
0a20: 65 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  en.** backwards 
0a30: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73  compatibility is
0a40: 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69   broken and we i
0a50: 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72 20 62  ntend to never b
0a60: 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77 61 72 64  reak.** backward
0a70: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
0a80: 20 20 54 68 65 20 59 20 76 61 6c 75 65 20 6f 6e    The Y value on
0a90: 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e 0a  ly changes when.
0aa0: 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61 6a  ** there are maj
0ab0: 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61 6e  or feature enhan
0ac0: 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  cements that are
0ad0: 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61 74   forwards compat
0ae0: 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ible.** but not 
0af0: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0b00: 69 62 6c 65 2e 20 20 54 68 65 20 5a 20 76 61 6c  ible.  The Z val
0b10: 75 65 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  ue is incremente
0b20: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0b30: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0b40: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0b50: 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65   Y is incremente
0b60: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
0b70: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0b80: 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ER is an integer
0b90: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0ba0: 0a 2a 2a 20 28 58 2a 31 30 30 30 30 30 30 20 2b  .** (X*1000000 +
0bb0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 2e 20 46 6f   Y*1000 + Z). Fo
0bc0: 72 20 65 78 61 6d 70 6c 65 2c 20 66 6f 72 20 76  r example, for v
0bd0: 65 72 73 69 6f 6e 20 22 33 2e 31 2e 31 62 65 74  ersion "3.1.1bet
0be0: 61 22 2c 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 56  a", .** SQLITE_V
0bf0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 69 73  ERSION_NUMBER is
0c00: 20 73 65 74 20 74 6f 20 33 30 30 31 30 30 31 2e   set to 3001001.
0c10: 20 54 6f 20 64 65 74 65 63 74 20 69 66 20 74 68   To detect if th
0c20: 65 79 20 61 72 65 20 75 73 69 6e 67 20 0a 2a 2a  ey are using .**
0c30: 20 76 65 72 73 69 6f 6e 20 33 2e 31 2e 31 20 6f   version 3.1.1 o
0c40: 72 20 67 72 65 61 74 65 72 20 61 74 20 63 6f 6d  r greater at com
0c50: 70 69 6c 65 20 74 69 6d 65 2c 20 70 72 6f 67 72  pile time, progr
0c60: 61 6d 73 20 6d 61 79 20 75 73 65 20 74 68 65 20  ams may use the 
0c70: 74 65 73 74 20 0a 2a 2a 20 28 53 51 4c 49 54 45  test .** (SQLITE
0c80: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 3e  _VERSION_NUMBER>
0c90: 3d 33 30 30 31 30 30 31 29 2e 0a 2a 2a 0a 2a 2a  =3001001)..**.**
0ca0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
0cb0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
0cc0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c  ] and [sqlite3_l
0cd0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
0ce0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
0cf0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20  SQLITE_VERSION  
0d00: 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d         "--VERS--
0d10: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ".#define SQLITE
0d20: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0d30: 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52  --VERSION-NUMBER
0d40: 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  --../*.** CAPI3R
0d50: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
0d60: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0d70: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  bers.**.** These
0d80: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
0d90: 20 76 61 6c 75 65 73 20 65 71 75 69 76 61 6c 65   values equivale
0da0: 6e 74 20 74 6f 20 74 68 65 20 68 65 61 64 65 72  nt to the header
0db0: 20 63 6f 6e 73 74 61 6e 74 73 0a 2a 2a 20 5b 53   constants.** [S
0dc0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 61  QLITE_VERSION] a
0dd0: 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  nd [SQLITE_VERSI
0de0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 54 68 65  ON_NUMBER].  The
0df0: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
0e00: 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
0e10: 69 6e 65 73 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  ines should only
0e20: 20 62 65 20 64 69 66 66 65 72 65 6e 74 20 66 72   be different fr
0e30: 6f 6d 20 74 68 65 20 68 65 61 64 65 72 20 76 61  om the header va
0e40: 6c 75 65 73 0a 2a 2a 20 69 66 20 79 6f 75 20 63  lues.** if you c
0e50: 6f 6d 70 69 6c 65 20 79 6f 75 72 20 70 72 6f 67  ompile your prog
0e60: 72 61 6d 20 75 73 69 6e 67 20 61 6e 20 73 71 6c  ram using an sql
0e70: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 72  ite3.h header fr
0e80: 6f 6d 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e  om a.** differen
0e90: 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  t version of SQL
0ea0: 69 74 65 20 74 68 61 74 20 74 68 65 20 76 65 72  ite that the ver
0eb0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 6c 69 62 72  sion of the libr
0ec0: 61 72 79 20 79 6f 75 0a 2a 2a 20 6c 69 6e 6b 20  ary you.** link 
0ed0: 61 67 61 69 6e 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  against..**.** T
0ee0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
0ef0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
0f00: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
0f10: 65 20 74 65 78 74 20 6f 66 20 74 68 65 0a 2a 2a  e text of the.**
0f20: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0f30: 5d 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 73  ] string.  The s
0f40: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
0f50: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
0f60: 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 65 72  urns.** a poiner
0f70: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
0f80: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
0f90: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
0fa0: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 70  function.** is p
0fb0: 72 6f 76 69 64 65 64 20 66 6f 72 20 44 4c 4c 20  rovided for DLL 
0fc0: 75 73 65 72 73 20 77 68 6f 20 63 61 6e 20 6f 6e  users who can on
0fd0: 6c 79 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  ly access functi
0fe0: 6f 6e 73 20 61 6e 64 20 6e 6f 74 0a 2a 2a 20 63  ons and not.** c
0ff0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1000: 74 68 65 20 44 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49  the DLL..*/.SQLI
1010: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
1020: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
1030: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
1040: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
1050: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e  ersion(void);.in
1060: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
1070: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
1080: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1090: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
10a0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
10b0: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53  *.** Each open S
10c0: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69  QLite database i
10d0: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  s represented by
10e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
10f0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a 2a  nstance of the.*
1100: 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  * opaque structu
1110: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
1120: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
1130: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
1140: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
1150: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
1160: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
1170: 6f 70 65 6e 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  open], [sqlite3_
1180: 6f 70 65 6e 31 36 5d 2c 20 61 6e 64 0a 2a 2a 20  open16], and.** 
1190: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
11a0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
11b0: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
11c0: 73 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  s.** and [sqlite
11d0: 33 5f 63 6c 6f 73 65 5d 20 69 73 20 69 74 73 20  3_close] is its 
11e0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
11f0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
1200: 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
1210: 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74 65  (such as [sqlite
1220: 33 5f 70 72 65 70 61 72 65 5f 76 32 5d 2c 20 5b  3_prepare_v2], [
1230: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
1240: 75 6e 63 74 69 6f 6e 5d 2c 20 61 6e 64 0a 2a 2a  unction], and.**
1250: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1260: 69 6d 65 6f 75 74 5d 20 74 6f 20 6e 61 6d 65 20  imeout] to name 
1270: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
1280: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74  are methods on t
1290: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a  his.** object..*
12a0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
12b0: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
12c0: 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
12d0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
12e0: 65 72 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 53  er Types.**.** S
12f0: 6f 6d 65 20 63 6f 6d 70 69 6c 65 72 73 20 64 6f  ome compilers do
1300: 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65   not support the
1310: 20 22 6c 6f 6e 67 20 6c 6f 6e 67 22 20 64 61 74   "long long" dat
1320: 61 74 79 70 65 2e 20 20 53 6f 20 77 65 20 68 61  atype.  So we ha
1330: 76 65 0a 2a 2a 20 74 6f 20 64 6f 20 63 6f 6d 70  ve.** to do comp
1340: 69 6c 65 72 2d 73 70 65 63 69 66 69 63 20 74 79  iler-specific ty
1350: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
1360: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
1370: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
1380: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
1390: 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
13a0: 74 69 6f 6e 73 20 72 65 71 75 69 72 65 20 61 20  tions require a 
13b0: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 61  64-bit integer a
13c0: 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 6f  rguments..** Tho
13d0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  se interfaces ar
13e0: 65 20 64 65 63 6c 61 72 65 64 20 75 73 69 6e 67  e declared using
13f0: 20 74 68 69 73 20 74 79 70 65 64 65 66 2e 0a 2a   this typedef..*
1400: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
1410: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
1420: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
1430: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
1440: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
1450: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
1460: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
1470: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
1480: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
1490: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
14a0: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
14b0: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
14c0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
14d0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
14e0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
14f0: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
1500: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
1510: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
1520: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
1530: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
1540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1550: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
1560: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
1570: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
1580: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
1590: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
15a0: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
15b0: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
15c0: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
15d0: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
15e0: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
15f0: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
1600: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
1610: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
1620: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f  E_OMIT_FLOATING_
1630: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64  POINT.# define d
1640: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e  ouble sqlite3_in
1650: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  t64.#endif../*.*
1660: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73  * CAPI3REF: Clos
1670: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43  ing A Database C
1680: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
1690: 43 61 6c 6c 20 74 68 69 73 20 66 75 6e 63 74 69  Call this functi
16a0: 6f 6e 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  on with a pointe
16b0: 72 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  r to a structure
16c0: 20 74 68 61 74 20 77 61 73 20 70 72 65 76 69 6f   that was previo
16d0: 75 73 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  usly.** returned
16e0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f   from [sqlite3_o
16f0: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1700: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  _open16()], or.*
1710: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1720: 76 32 28 29 5d 20 61 6e 64 20 74 68 65 20 63 6f  v2()] and the co
1730: 72 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61  rresponding data
1740: 62 61 73 65 20 77 69 6c 6c 20 62 79 0a 2a 2a 20  base will by.** 
1750: 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6c  closed..**.** Al
1760: 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  l SQL statements
1770: 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
1780: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1790: 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
17a0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
17b0: 76 32 28 29 5d 20 6d 75 73 74 20 62 65 20 64 65  v2()] must be de
17c0: 73 74 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73  stroyed using [s
17d0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
17e0: 29 5d 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69  )].** before thi
17f0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  s routine is cal
1800: 6c 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20  led. Otherwise, 
1810: 53 51 4c 49 54 45 5f 42 55 53 59 20 69 73 20 72  SQLITE_BUSY is r
1820: 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 0a  eturned and the.
1830: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1840: 65 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 6f  ection remains o
1850: 70 65 6e 2e 0a 2a 2a 0a 2a 2a 20 50 61 73 73 69  pen..**.** Passi
1860: 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1870: 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1880: 63 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 61  ction that has a
1890: 6c 72 65 61 64 79 20 62 65 65 6e 0a 2a 2a 20 63  lready been.** c
18a0: 6c 6f 73 65 64 20 72 65 73 75 6c 74 73 20 69 6e  losed results in
18b0: 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
18c0: 69 6f 72 2e 20 20 49 66 20 6f 74 68 65 72 20 69  ior.  If other i
18d0: 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 0a 2a  nterfaces that.*
18e0: 2a 20 72 65 66 65 72 65 6e 63 65 20 74 68 65 20  * reference the 
18f0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1900: 6e 6e 65 63 74 69 6f 6e 20 61 72 65 20 70 65 6e  nnection are pen
1910: 64 69 6e 67 20 28 65 69 74 68 65 72 20 69 6e 20  ding (either in 
1920: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 74 68 72 65  the.** same thre
1930: 61 64 20 6f 72 20 69 6e 20 64 69 66 66 65 72 65  ad or in differe
1940: 6e 74 20 74 68 72 65 61 64 73 29 20 77 68 65 6e  nt threads) when
1950: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
1960: 20 63 61 6c 6c 65 64 2c 0a 2a 2a 20 74 68 65 6e   called,.** then
1970: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1980: 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 69   undefined and i
1990: 73 20 61 6c 6d 6f 73 74 20 63 65 72 74 61 69 6e  s almost certain
19a0: 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
19b0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
19c0: 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b  lose(sqlite3 *);
19d0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ../*.** The type
19e0: 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20   for a callback 
19f0: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69  function..** Thi
1a00: 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20  s is legacy and 
1a10: 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20  deprecated.  It 
1a20: 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20  is included for 
1a30: 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f  historical.** co
1a40: 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20  mpatibility and 
1a50: 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65  is not documente
1a60: 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e  d..*/.typedef in
1a70: 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c  t (*sqlite3_call
1a80: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
1a90: 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b  char**, char**);
1aa0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ab0: 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79  : One-Step Query
1ac0: 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72   Execution Inter
1ad0: 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  face.**.** This 
1ae0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
1af0: 64 20 74 6f 20 64 6f 20 61 20 6f 6e 65 2d 74 69  d to do a one-ti
1b00: 6d 65 20 65 76 61 6c 75 61 74 61 74 69 6f 6e 20  me evaluatation 
1b10: 6f 66 20 7a 65 72 6f 0a 2a 2a 20 6f 72 20 6d 6f  of zero.** or mo
1b20: 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
1b30: 73 2e 20 20 55 54 46 2d 38 20 74 65 78 74 20 6f  s.  UTF-8 text o
1b40: 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
1b50: 65 6e 74 73 20 74 6f 0a 2a 2a 20 62 65 20 65 76  ents to.** be ev
1b60: 61 6c 75 74 65 64 20 69 73 20 70 61 73 73 65 64  aluted is passed
1b70: 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e   in as the secon
1b80: 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
1b90: 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
1ba0: 61 72 65 20 70 72 65 70 61 72 65 64 20 6f 6e 65  are prepared one
1bb0: 20 62 79 20 6f 6e 65 20 75 73 69 6e 67 20 5b 73   by one using [s
1bc0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1bd0: 5d 2c 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20  ], evaluated.** 
1be0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
1bf0: 74 65 70 28 29 5d 2c 20 74 68 65 6e 20 64 65 73  tep()], then des
1c00: 74 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 71  troyed using [sq
1c10: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1c20: 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 6e 65 20  ]..**.** If one 
1c30: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53  or more of the S
1c40: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
1c50: 65 20 71 75 65 72 69 65 73 2c 20 74 68 65 6e 0a  e queries, then.
1c60: 2a 2a 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** the callback 
1c70: 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69  function specifi
1c80: 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61  ed by the 3rd pa
1c90: 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 69 6e  rameter is.** in
1ca0: 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  voked once for e
1cb0: 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 71  ach row of the q
1cc0: 75 65 72 79 20 72 65 73 75 6c 74 2e 20 20 54 68  uery result.  Th
1cd0: 69 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 73  is callback.** s
1ce0: 68 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20 72  hould normally r
1cf0: 65 74 75 72 6e 20 30 2e 20 20 49 66 20 74 68 65  eturn 0.  If the
1d00: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d10: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20  s a non-zero.** 
1d20: 76 61 6c 75 65 20 74 68 65 6e 20 74 68 65 20 71  value then the q
1d30: 75 65 72 79 20 69 73 20 61 62 6f 72 74 65 64 2c  uery is aborted,
1d40: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
1d50: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1d60: 2a 20 61 72 65 20 73 6b 69 70 70 65 64 20 61 6e  * are skipped an
1d70: 64 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  d the sqlite3_ex
1d80: 65 63 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  ec() function re
1d90: 74 75 72 6e 73 20 74 68 65 20 53 51 4c 49 54 45  turns the SQLITE
1da0: 5f 41 42 4f 52 54 2e 0a 2a 2a 0a 2a 2a 20 54 68  _ABORT..**.** Th
1db0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
1dc0: 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  to this interfac
1dd0: 65 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  e is an arbitrar
1de0: 79 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  y pointer that i
1df0: 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
1e00: 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
1e10: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  ack function as 
1e20: 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  its first parame
1e30: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 32  ter..**.** The 2
1e40: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1e50: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
1e60: 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6e 75 6d  ction is the num
1e70: 62 65 72 20 6f 66 0a 2a 2a 20 63 6f 6c 75 6d 6e  ber of.** column
1e80: 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 72  s in the query r
1e90: 65 73 75 6c 74 2e 20 20 54 68 65 20 33 72 64 20  esult.  The 3rd 
1ea0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1eb0: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1ec0: 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74 72 69  an array of stri
1ed0: 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 20  ngs holding the 
1ee0: 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20  values for each 
1ef0: 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 73 20 65 78 74  column.** as ext
1f00: 72 61 63 74 65 64 20 75 73 69 6e 67 20 5b 73 71  racted using [sq
1f10: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1f20: 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 34 74 68  t()]..** The 4th
1f30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1f40: 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1f50: 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67   array of string
1f60: 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 75 73  s.** obtained us
1f70: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  ing [sqlite3_col
1f80: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20  umn_name()] and 
1f90: 68 6f 6c 64 69 6e 67 0a 2a 2a 20 74 68 65 20 6e  holding.** the n
1fa0: 61 6d 65 73 20 6f 66 20 65 61 63 68 20 63 6f 6c  ames of each col
1fb0: 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  umn..**.** The c
1fc0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1fd0: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 65 76   may be NULL, ev
1fe0: 65 6e 20 66 6f 72 20 71 75 65 72 69 65 73 2e 20  en for queries. 
1ff0: 20 41 20 4e 55 4c 4c 0a 2a 2a 20 63 61 6c 6c 62   A NULL.** callb
2000: 61 63 6b 20 69 73 20 6e 6f 74 20 61 6e 20 65 72  ack is not an er
2010: 72 6f 72 2e 20 20 49 74 20 6a 75 73 74 20 6d 65  ror.  It just me
2020: 61 6e 73 20 74 68 61 74 20 6e 6f 20 63 61 6c 6c  ans that no call
2030: 62 61 63 6b 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  back.** will be 
2040: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  invoked..**.** I
2050: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
2060: 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20  s while parsing 
2070: 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  or evaluating th
2080: 65 20 53 51 4c 20 28 62 75 74 0a 2a 2a 20 6e 6f  e SQL (but.** no
2090: 74 20 77 68 69 6c 65 20 65 78 65 63 75 74 69 6e  t while executin
20a0: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 29 20  g the callback) 
20b0: 74 68 65 6e 20 61 6e 20 61 70 70 72 6f 70 72 69  then an appropri
20c0: 61 74 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  ate error.** mes
20d0: 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20  sage is written 
20e0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
20f0: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2100: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
2110: 0a 2a 2a 20 2a 65 72 72 6d 73 67 20 69 73 20 6d  .** *errmsg is m
2120: 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
2130: 74 68 61 74 20 6d 65 73 73 61 67 65 2e 20 20 54  that message.  T
2140: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
2150: 69 6f 6e 0a 2a 2a 20 69 73 20 72 65 73 70 6f 6e  ion.** is respon
2160: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
2170: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  g the memory tha
2180: 74 20 68 6f 6c 64 73 20 74 68 65 20 65 72 72 6f  t holds the erro
2190: 72 0a 2a 2a 20 6d 65 73 73 61 67 65 2e 20 20 20  r.** message.   
21a0: 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  Use [sqlite3_fre
21b0: 65 28 29 5d 20 66 6f 72 20 74 68 69 73 2e 20 20  e()] for this.  
21c0: 49 66 20 65 72 72 6d 73 67 3d 3d 4e 55 4c 4c 2c  If errmsg==NULL,
21d0: 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 65 72 72 6f  .** then no erro
21e0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 65 76 65  r message is eve
21f0: 72 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a  r written..**.**
2200: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
2210: 65 20 69 73 20 69 73 20 53 51 4c 49 54 45 5f 4f  e is is SQLITE_O
2220: 4b 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e  K if there are n
2230: 6f 20 65 72 72 6f 72 73 20 61 6e 64 0a 2a 2a 20  o errors and.** 
2240: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 53 51 4c 49  some other [SQLI
2250: 54 45 5f 4f 4b 20 7c 20 72 65 74 75 72 6e 20 63  TE_OK | return c
2260: 6f 64 65 5d 20 69 66 20 74 68 65 72 65 20 69 73  ode] if there is
2270: 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 20   an error.  .** 
2280: 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 72  The particular r
2290: 65 74 75 72 6e 20 76 61 6c 75 65 20 64 65 70 65  eturn value depe
22a0: 6e 64 73 20 6f 6e 20 74 68 65 20 74 79 70 65 20  nds on the type 
22b0: 6f 66 20 65 72 72 6f 72 2e 20 0a 2a 2a 0a 2a 2f  of error. .**.*/
22c0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65  .int sqlite3_exe
22d0: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
22e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2300: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
2310: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
2320: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
2330: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2340: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
2350: 20 65 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69   evaluted */.  i
2360: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
2370: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
2380: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
2390: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
23a0: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
23b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
23d0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
23e0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
23f0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
2400: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2410: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
2420: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
2430: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
2440: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
2450: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
2460: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 0a  ORDS: SQLITE_OK.
2470: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
2480: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2490: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
24a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
24b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
24c0: 61 62 6f 76 65 20 69 6e 20 6f 72 64 65 72 20 74  above in order t
24d0: 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63  o indicates succ
24e0: 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a  ess or failure..
24f0: 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 73 75 6c 74  **.** The result
2500: 20 63 6f 64 65 73 20 61 62 6f 76 65 20 61 72 65   codes above are
2510: 20 74 68 65 20 6f 6e 6c 79 20 6f 6e 65 73 20 72   the only ones r
2520: 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
2530: 65 20 69 6e 20 69 74 73 0a 2a 2a 20 64 65 66 61  e in its.** defa
2540: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
2550: 6e 2e 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65  n.  However, the
2560: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
2570: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
2580: 29 5d 0a 2a 2a 20 41 50 49 20 63 61 6e 20 62 65  )].** API can be
2590: 20 75 73 65 64 20 74 6f 20 73 65 74 20 61 20 64   used to set a d
25a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 6f  atabase connecto
25b0: 69 6e 20 74 6f 20 72 65 74 75 72 6e 20 6d 6f 72  in to return mor
25c0: 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 72 65  e detailed.** re
25d0: 73 75 6c 74 20 63 6f 64 65 73 2e 0a 2a 2a 0a 2a  sult codes..**.*
25e0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
25f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
2600: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
2610: 20 63 6f 64 65 73 5d 0a 2a 2a 0a 2a 2f 0a 23 64   codes].**.*/.#d
2620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20  efine SQLITE_OK 
2630: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
2640: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
2650: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69  lt */./* beginni
2660: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  ng-of-error-code
2670: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
2680: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20  ITE_ERROR       
2690: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f   1   /* SQL erro
26a0: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74  r or missing dat
26b0: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
26c0: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c   SQLITE_INTERNAL
26d0: 20 20 20 20 20 32 20 20 20 2f 2a 20 4e 4f 54 20       2   /* NOT 
26e0: 55 53 45 44 2e 20 49 6e 74 65 72 6e 61 6c 20 6c  USED. Internal l
26f0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
2700: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
2710: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
2720: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
2730: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
2740: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
2750: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
2760: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
2770: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
2780: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
2790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27a0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
27b0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
27c0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
27d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
27e0: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
27f0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
2800: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
2810: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
2820: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
2830: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
2840: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
2850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2860: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
2870: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
2880: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
2890: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
28a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
28b0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
28c0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
28d0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
28e0: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
28f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
2900: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
2910: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
2920: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
2930: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
2940: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
2950: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
2960: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
2970: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
2980: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
2990: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
29a0: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44  12   /* NOT USED
29b0: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72  . Table or recor
29c0: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23  d not found */.#
29d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
29e0: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f  LL        13   /
29f0: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  * Insertion fail
2a00: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62  ed because datab
2a10: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23  ase is full */.#
2a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
2a30: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f  NTOPEN    14   /
2a40: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e  * Unable to open
2a50: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2a60: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
2a70: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20  LITE_PROTOCOL   
2a80: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   15   /* NOT USE
2a90: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  D. Database lock
2aa0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
2ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2ac0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
2ad0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
2ae0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
2af0: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
2b00: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
2b10: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2b20: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
2b30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
2b40: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
2b50: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
2b60: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
2b70: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
2b80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
2b90: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
2ba0: 65 20 74 6f 20 63 6f 6e 74 72 61 69 6e 74 20 76  e to contraint v
2bb0: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
2bc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
2bd0: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
2be0: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
2bf0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
2c00: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
2c10: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
2c20: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
2c30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2c40: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
2c50: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
2c60: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
2c70: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
2c80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c90: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
2ca0: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
2cb0: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
2cc0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
2cd0: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
2ce0: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
2cf0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
2d00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2d10: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
2d20: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
2d30: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2d40: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
2d50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2d60: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
2d70: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
2d80: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
2d90: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
2da0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2db0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
2dc0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
2dd0: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
2de0: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
2df0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
2e00: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
2e10: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
2e20: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2e30: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
2e40: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
2e50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e60: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
2e70: 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 49 6e  t Codes.**.** In
2e80: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
2e90: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
2ea0: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
2eb0: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
2ec0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 72 65 73 75   integer.** resu
2ed0: 6c 74 20 63 6f 64 65 73 20 64 65 73 63 72 69 62  lt codes describ
2ee0: 65 64 20 61 74 20 72 65 73 75 6c 74 2d 63 6f 64  ed at result-cod
2ef0: 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  es.  However, ex
2f00: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
2f10: 77 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20  wn that.** many 
2f20: 6f 66 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  of these result 
2f30: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
2f40: 75 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  urse-grained.  T
2f50: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
2f60: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
2f70: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2f80: 70 72 6f 62 6c 65 6d 73 20 61 73 20 75 73 65 72  problems as user
2f90: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
2fa0: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
2fb0: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
2fc0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
2fd0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
2fe0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
2ff0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
3000: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
3010: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
3020: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
3030: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
3040: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
3050: 74 20 65 72 72 6f 72 73 2e 20 20 54 68 65 20 65  t errors.  The e
3060: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3070: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
3080: 20 28 6f 72 20 64 69 73 61 62 6c 65 64 29 20 66   (or disabled) f
3090: 6f 72 20 0a 2a 2a 20 65 61 63 68 20 64 61 74 61  or .** each data
30a0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
30b0: 6f 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  on using the [sq
30c0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
30d0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
30e0: 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20  PI..** .** Some 
30f0: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  of the available
3100: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
3110: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65   codes are liste
3120: 64 20 61 62 6f 76 65 2e 0a 2a 2a 20 57 65 20 65  d above..** We e
3130: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
3140: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
3150: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
3160: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
3170: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
3180: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
3190: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
31a0: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
31b0: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
31c0: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
31d0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
31e0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 0a 2a 2a 20 54  SQLite..** .** T
31f0: 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
3200: 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64   for an extended
3210: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77   result code alw
3220: 61 79 73 20 63 6f 6e 74 61 69 6e 73 20 61 20 72  ays contains a r
3230: 65 6c 61 74 65 64 0a 2a 2a 20 70 72 69 6d 61 72  elated.** primar
3240: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73  y result code as
3250: 20 61 20 70 72 65 66 69 78 2e 20 20 50 72 69 6d   a prefix.  Prim
3260: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ary result codes
3270: 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c   contain a singl
3280: 65 0a 2a 2a 20 22 5f 22 20 63 68 61 72 61 63 74  e.** "_" charact
3290: 65 72 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65  er.  Extended re
32a0: 73 75 6c 74 20 63 6f 64 65 73 20 63 6f 6e 74 61  sult codes conta
32b0: 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22  in two or more "
32c0: 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  _" characters..*
32d0: 2a 20 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61  * The numeric va
32e0: 6c 75 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64  lue of an extend
32f0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63  ed result code c
3300: 61 6e 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  an be converted 
3310: 74 6f 20 69 74 73 0a 2a 2a 20 63 6f 72 72 65 73  to its.** corres
3320: 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20  ponding primary 
3330: 72 65 73 75 6c 74 20 63 6f 64 65 20 62 79 20 6d  result code by m
3340: 61 73 6b 69 6e 67 20 6f 66 66 20 74 68 65 20 6c  asking off the l
3350: 6f 77 65 72 20 38 20 62 79 74 65 73 2e 0a 2a 2a  ower 8 bytes..**
3360: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
3370: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
3380: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
3390: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
33a0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
33b0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
33c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
33d0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
33e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
33f0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
3400: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
3410: 52 54 5f 52 45 41 44 20 20 20 20 28 53 51 4c 49  RT_READ    (SQLI
3420: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
3430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3440: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
3450: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3460: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
3470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3480: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
3490: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
34a0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
34b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
34c0: 52 5f 46 53 59 4e 43 20 20 20 20 20 28 53 51 4c  R_FSYNC     (SQL
34d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c  ITE_IOERR | (5<<
34e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
34f0: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54  TE_IOERR_TRUNCAT
3500: 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49  E      (SQLITE_I
3510: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
3520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3530: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
3540: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3550: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
3560: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
3570: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51  NLOCK        (SQ
3580: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
3590: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
35a0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
35b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
35c0: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a  IOERR | (9<<8)).
35d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
35e0: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20  OERR_DELETE     
35f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
3600: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
3610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3620: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 28  _BLOCKED       (
3630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3640: 31 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  11<<8))../*.** C
3650: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
3660: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
3670: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 43 6f  rations.**.** Co
3680: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65  mbination of the
3690: 20 66 6f 6c 6c 6f 77 69 6e 67 20 62 69 74 20 76   following bit v
36a0: 61 6c 75 65 73 20 61 72 65 20 75 73 65 64 20 61  alues are used a
36b0: 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 61  s the.** third a
36c0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
36d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
36e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
36f0: 0a 2a 2a 20 61 73 20 66 6f 75 72 74 68 20 61 72  .** as fourth ar
3700: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 78 4f  gument to the xO
3710: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  pen method of th
3720: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
3730: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2f  s] object..**.*/
3740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3750: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
3760: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
3770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3780: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
3790: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
37a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37b0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
37c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
37d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37e0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
37f0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
3800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3810: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
3820: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
3830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3840: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
3850: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
3860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3870: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
3880: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
3890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38a0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
38b0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  L     0x00000400
38c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38d0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
38e0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
38f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3900: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
3910: 20 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30        0x00001000
3920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3930: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
3940: 4e 41 4c 20 20 20 30 78 30 30 30 30 32 30 30 30  NAL   0x00002000
3950: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
3960: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
3970: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
3980: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69  he xDeviceCapabi
3990: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66  lities method of
39a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
39b0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
39c0: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
39d0: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
39e0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20  a vector of the 
39f0: 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 62 69 74  following.** bit
3a00: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
3a10: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
3a20: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
3a30: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
3a40: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
3a50: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
3a60: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
3a70: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
3a80: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
3a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
3aa0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
3ab0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
3ac0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
3ad0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
3ae0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
3af0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
3b00: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
3b10: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
3b20: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
3b30: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
3b40: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
3b50: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
3b60: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
3b70: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
3b80: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
3b90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
3ba0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
3bb0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
3bc0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
3bd0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
3be0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
3bf0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
3c00: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
3c10: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
3c20: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
3c30: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
3c40: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
3c50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
3c60: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
3c70: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
3c80: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
3c90: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
3ca0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
3cb0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
3cc0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
3cd0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3ce0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
3cf0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
3d00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3d10: 35 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30  512       0x0000
3d20: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
3d30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3d40: 31 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  1K        0x0000
3d50: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
3d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3d70: 32 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  2K        0x0000
3d80: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
3d90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3da0: 34 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  4K        0x0000
3db0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
3dc0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3dd0: 38 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  8K        0x0000
3de0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
3df0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3e00: 31 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30  16K       0x0000
3e10: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
3e20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3e30: 33 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30  32K       0x0000
3e40: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
3e50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3e60: 36 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30  64K       0x0000
3e70: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
3e80: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
3e90: 50 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30  PPEND     0x0000
3ea0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
3eb0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
3ec0: 54 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30  TIAL      0x0000
3ed0: 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0400../*.** CAPI
3ee0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
3ef0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
3f00: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
3f10: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
3f20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
3f30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
3f40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
3f50: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
3f60: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
3f70: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
3f80: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
3f90: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
3fa0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
3fb0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
3fc0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
3fd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
3fe0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
3ff0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
4000: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
4010: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
4020: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
4030: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
4040: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
4050: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
4060: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
4070: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
4080: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
4090: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
40a0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
40b0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
40c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
40d0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 74 20 75  ].** object it u
40e0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
40f0: 6e 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  n of the followi
4100: 6e 67 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ng integer value
4110: 73 20 61 73 0a 2a 2a 20 74 68 65 20 73 65 63 6f  s as.** the seco
4120: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
4130: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
4140: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
4150: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
4160: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
4170: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
4180: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
4190: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
41a0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
41b0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
41c0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
41d0: 6c 75 73 68 65 64 2e 20 20 54 68 65 20 53 51 4c  lushed.  The SQL
41e0: 49 54 45 5f 53 59 4e 43 5f 42 41 52 52 49 45 52  ITE_SYNC_BARRIER
41f0: 20 66 6c 61 67 0a 2a 2a 20 6d 65 61 6e 73 20 74   flag.** means t
4200: 68 61 74 20 74 68 65 20 6e 6f 74 68 69 6e 67 20  hat the nothing 
4210: 61 63 74 75 61 6c 6c 79 20 6e 65 65 64 73 20 74  actually needs t
4220: 6f 20 62 65 20 73 79 6e 63 68 65 64 20 74 6f 20  o be synched to 
4230: 6d 61 73 73 20 73 74 6f 72 61 67 65 2c 0a 2a 2a  mass storage,.**
4240: 20 62 75 74 20 61 6c 6c 20 77 72 69 74 65 20 6f   but all write o
4250: 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 6f  perations that o
4260: 63 63 75 72 20 62 65 66 6f 72 65 20 74 68 65 20  ccur before the 
4270: 62 61 72 72 69 65 72 20 6d 75 73 74 20 63 6f 6d  barrier must com
4280: 70 6c 65 74 65 0a 2a 2a 20 62 65 66 6f 72 65 20  plete.** before 
4290: 61 6e 79 20 77 72 69 74 65 20 6f 70 65 72 61 74  any write operat
42a0: 69 6f 6e 73 20 74 68 61 74 20 6f 63 63 75 72 20  ions that occur 
42b0: 61 66 74 65 72 20 74 68 65 20 62 61 72 72 69 65  after the barrie
42c0: 72 20 62 65 67 69 6e 2e 0a 2a 2a 20 54 68 65 20  r begin..** The 
42d0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
42e0: 41 4c 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  AL means to use 
42f0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
4300: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 54 68 65  emantics..** The
4310: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
4320: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 6f 20  L flag means to 
4330: 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79  use Mac OS-X sty
4340: 6c 65 20 66 75 6c 6c 73 79 6e 63 0a 2a 2a 20 69  le fullsync.** i
4350: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
4360: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
4370: 4c 49 54 45 5f 53 59 4e 43 5f 42 41 52 52 49 45  LITE_SYNC_BARRIE
4380: 52 20 20 20 20 20 20 20 30 78 30 30 30 30 31 0a  R       0x00001.
4390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
43a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
43b0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
43c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
43d0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
43e0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
43f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
4400: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 0a        0x00010...
4410: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4420: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
4430: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
4440: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
4450: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
4460: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
4470: 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a  file in the OS.*
4480: 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  * interface laye
4490: 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  r.  Individual O
44a0: 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c  S interface impl
44b0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
44c0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
44d0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
44e0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
44f0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
4500: 2a 2a 20 6f 66 20 74 68 65 69 72 20 6f 77 6e 20  ** of their own 
4510: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
4520: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
4530: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
4540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
4550: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
4560: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
4570: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
4580: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
4590: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
45a0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
45b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
45c0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
45d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
45e0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
45f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
4600: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
4610: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
4620: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
4630: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
4640: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
4650: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
4660: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
4670: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6f 70 65 6e  **.** Every open
4680: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 5b 73 71   file in the [sq
4690: 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e  lite3_vfs] xOpen
46a0: 20 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73   method contains
46b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
46c0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
46d0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 62  the following ob
46e0: 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
46f0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 0a 2a  ct defines the.*
4700: 2a 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  * methods used t
4710: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
4720: 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 67 61  s operations aga
4730: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
4740: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  le..**.** The fl
4750: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
4760: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
4770: 20 6f 66 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f   of SQLITE_SYNC_
4780: 42 41 52 52 49 45 52 2c 0a 2a 2a 20 53 51 4c 49  BARRIER,.** SQLI
4790: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
47a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
47b0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
47c0: 69 63 65 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  ice means that.*
47d0: 2a 20 64 61 74 61 20 69 73 20 6e 6f 74 20 6e 65  * data is not ne
47e0: 63 65 73 73 61 72 69 6c 79 20 73 79 6e 63 65 64  cessarily synced
47f0: 20 74 6f 20 64 69 73 6b 20 63 6f 6d 70 6c 65 74   to disk complet
4800: 65 6c 79 2c 20 6f 6e 6c 79 20 74 68 61 74 0a 2a  ely, only that.*
4810: 2a 20 61 6c 6c 20 77 72 69 74 65 73 20 74 68 61  * all writes tha
4820: 74 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 74  t occur before t
4830: 68 65 20 73 79 6e 63 20 63 6f 6d 70 6c 65 74 65  he sync complete
4840: 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 77   before any.** w
4850: 72 69 74 65 73 20 74 68 61 74 20 6f 63 63 75 72  rites that occur
4860: 20 61 66 74 65 72 20 74 68 65 20 73 79 6e 63 2e   after the sync.
4870: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 66 6c 61    The second fla
4880: 67 20 69 73 20 74 68 65 0a 2a 2a 20 6e 6f 72 6d  g is the.** norm
4890: 61 6c 20 66 73 79 6e 63 28 29 2e 20 20 54 68 65  al fsync().  The
48a0: 20 74 68 69 72 64 20 66 6c 61 67 20 69 73 20 61   third flag is a
48b0: 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS-X style full
48c0: 73 79 6e 63 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  sync..** The SQL
48d0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66 6c  ITE_SYNC_DATA fl
48e0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
48f0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
4900: 61 74 20 6f 6e 6c 79 0a 2a 2a 20 74 68 65 20 64  at only.** the d
4910: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ata of the file 
4920: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
4930: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
4940: 6e 63 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  nced..** .** The
4950: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
4960: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
4970: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
4980: 20 6f 66 0a 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f   of.** SQLITE_LO
4990: 43 4b 5f 4e 4f 4e 45 2c 20 53 51 4c 49 54 45 5f  CK_NONE, SQLITE_
49a0: 4c 4f 43 4b 5f 52 45 41 44 2c 20 53 51 4c 49 54  LOCK_READ, SQLIT
49b0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 2c  E_LOCK_RESERVED,
49c0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  .** SQLITE_LOCK_
49d0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 53 51 4c 49  PENDING, or SQLI
49e0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
49f0: 45 2e 20 20 78 4c 6f 63 6b 28 29 0a 2a 2a 20 69  E.  xLock().** i
4a00: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
4a10: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
4a20: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
4a30: 20 20 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b    .** The xCheck
4a40: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
4a50: 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a 20 74  ethod looks.** t
4a60: 6f 20 73 65 65 20 69 66 20 61 6e 79 20 64 61 74  o see if any dat
4a70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4a80: 2c 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  , either in this
4a90: 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72 20 69  .** process or i
4aa0: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
4ab0: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
4ac0: 20 61 6e 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a   an RESERVED,.**
4ad0: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
4ae0: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
4af0: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
4b00: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
4b10: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
4b20: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  ts and false if 
4b30: 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 78 42 72 65  not..** .** xBre
4b40: 61 6b 4c 6f 63 6b 28 29 20 61 74 74 65 6d 70 74  akLock() attempt
4b50: 73 20 74 6f 20 62 72 65 61 6b 20 61 20 6c 6f 63  s to break a loc
4b60: 6b 20 68 65 6c 64 20 62 79 20 61 6e 6f 74 68 65  k held by anothe
4b70: 72 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68  r process..** Th
4b80: 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  is can be used t
4b90: 6f 20 72 65 6d 6f 76 65 20 61 20 73 74 61 6c 65  o remove a stale
4ba0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 2c 20   dot-file lock, 
4bb0: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 0a 2a 2a 20  for example..** 
4bc0: 49 74 20 72 65 74 75 72 6e 73 20 30 20 6f 6e 20  It returns 0 on 
4bd0: 73 75 63 63 65 73 73 20 61 6e 64 20 6e 6f 6e 2d  success and non-
4be0: 7a 65 72 6f 20 66 6f 72 20 61 20 66 61 69 6c 75  zero for a failu
4bf0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  re..**.** The xS
4c00: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
4c10: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
4c20: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
4c30: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
4c40: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
4c50: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
4c60: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
4c70: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
4c80: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
4c90: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
4ca0: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
4cb0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
4cc0: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
4cd0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
4ce0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
4cf0: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
4d00: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
4d10: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
4d20: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
4d30: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
4d40: 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41  <li> SQLITE_IOCA
4d50: 50 5f 41 54 4f 4d 49 43 0a 2a 2a 20 3c 6c 69 3e  P_ATOMIC.** <li>
4d60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4d70: 4f 4d 49 43 35 31 32 0a 2a 2a 20 3c 6c 69 3e 20  OMIC512.** <li> 
4d80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4d90: 4d 49 43 31 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51  MIC1K.** <li> SQ
4da0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4db0: 43 32 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49  C2K.** <li> SQLI
4dc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
4dd0: 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45  K.** <li> SQLITE
4de0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 0a  _IOCAP_ATOMIC8K.
4df0: 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49  ** <li> SQLITE_I
4e00: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 0a 2a  OCAP_ATOMIC16K.*
4e10: 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f  * <li> SQLITE_IO
4e20: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 0a 2a 2a  CAP_ATOMIC32K.**
4e30: 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43   <li> SQLITE_IOC
4e40: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 0a 2a 2a 20  AP_ATOMIC64K.** 
4e50: 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41  <li> SQLITE_IOCA
4e60: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 0a 2a 2a  P_SAFE_APPEND.**
4e70: 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43   <li> SQLITE_IOC
4e80: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 0a 2a 2a  AP_SEQUENTIAL.**
4e90: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
4ea0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4eb0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
4ec0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
4ed0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
4ee0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
4ef0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4f00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
4f10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
4f20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
4f30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
4f40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
4f50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
4f60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
4f70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
4f80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
4f90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
4fa0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4fb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
4fc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
4fd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
4fe0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
4ff0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5000: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5010: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5020: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5030: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5040: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5050: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5060: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5070: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5080: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5090: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
50a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
50b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
50c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
50d0: 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
50e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
50f0: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
5100: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
5110: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
5120: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
5130: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
5140: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
5150: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
5160: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
5170: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
5180: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 5f 69  t iAmt, sqlite_i
5190: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
51a0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
51b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
51c0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
51d0: 74 2c 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  t, sqlite_int64 
51e0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
51f0: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
5200: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
5210: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
5220: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
5230: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
5240: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
5250: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
5260: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
5270: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
5280: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
5290: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
52a0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
52b0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
52c0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
52d0: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
52e0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
52f0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  le*);.  int (*xB
5300: 72 65 61 6b 4c 6f 63 6b 29 28 73 71 6c 69 74 65  reakLock)(sqlite
5310: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
5320: 28 2a 78 4c 6f 63 6b 53 74 61 74 65 29 28 73 71  (*xLockState)(sq
5330: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 29 3b 0a 20  lite3_file *);. 
5340: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
5350: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
5360: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
5370: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
5380: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
5390: 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f  *);.  /* Additio
53a0: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
53b0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
53c0: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
53d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
53e0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
53f0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
5400: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
5410: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
5420: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
5430: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
5440: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
5450: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
5460: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
5470: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
5480: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
5490: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
54a0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
54b0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
54c0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
54d0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
54e0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
54f0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
5500: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
5510: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
5520: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
5530: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
5540: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
5550: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
5560: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
5570: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
5580: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
5590: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
55a0: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
55b0: 61 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a  ace between the.
55c0: 2a 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  ** SQLite core a
55d0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
55e0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
55f0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
5600: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
5610: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
5620: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
5630: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a  file system"..**
5640: 0a 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e  .** The iVersion
5650: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
5660: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
5670: 20 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74 75   larger for futu
5680: 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
5690: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
56a0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
56b0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
56c0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
56d0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
56e0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
56f0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
5700: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
5710: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
5720: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
5730: 74 65 33 5f 66 69 6c 65 0a 2a 2a 20 73 74 72 75  te3_file.** stru
5740: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
5750: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
5760: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
5770: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
5780: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
5790: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 54 68  is VFS..**.** Th
57a0: 65 20 6e 52 65 66 20 66 69 65 6c 64 20 69 73 20  e nRef field is 
57b0: 69 6e 63 72 65 6d 65 6e 74 65 64 20 61 6e 64 20  incremented and 
57c0: 64 65 63 72 65 6d 65 6e 74 65 64 20 62 79 20 53  decremented by S
57d0: 51 4c 69 74 65 20 74 6f 20 6b 65 65 70 0a 2a 2a  QLite to keep.**
57e0: 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75   count of the nu
57f0: 6d 62 65 72 20 6f 66 20 75 73 65 72 73 20 6f 66  mber of users of
5800: 20 74 68 65 20 56 46 53 2e 20 20 54 68 69 73 20   the VFS.  This 
5810: 66 69 65 6c 64 20 61 6e 64 0a 2a 2a 20 76 66 73  field and.** vfs
5820: 4d 75 74 65 78 2c 20 70 4e 65 78 74 2c 20 61 6e  Mutex, pNext, an
5830: 64 20 70 50 72 65 76 20 61 72 65 20 74 68 65 20  d pPrev are the 
5840: 6f 6e 6c 79 20 66 69 65 6c 64 73 20 69 6e 20 74  only fields in t
5850: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 0a  he sqlite3_vfs .
5860: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
5870: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
5880: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
5890: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
58a0: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
58b0: 20 74 68 65 73 65 20 66 69 65 6c 64 73 20 77 68   these fields wh
58c0: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
58d0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
58e0: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
58f0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
5900: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
5910: 79 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20  y fields of the 
5920: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
5930: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
5940: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
5950: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 0a 2a  egistered..** .*
5960: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66  * The sqlite3_vf
5970: 73 2e 76 66 73 4d 75 74 65 78 20 69 73 20 61 20  s.vfsMutex is a 
5980: 6d 75 74 65 78 20 75 73 65 64 20 62 79 20 74 68  mutex used by th
5990: 65 20 4f 53 20 69 6e 74 65 72 66 61 63 65 2e 0a  e OS interface..
59a0: 2a 2a 20 49 74 20 73 68 6f 75 6c 64 20 69 6e 69  ** It should ini
59b0: 74 69 61 6c 6c 79 20 62 65 20 4e 55 4c 4c 2e 20  tially be NULL. 
59c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 69   SQLite will ini
59d0: 74 69 61 6c 69 7a 65 20 74 68 69 73 20 66 69 65  tialize this fie
59e0: 6c 64 0a 2a 2a 20 75 73 69 6e 67 20 73 71 6c 69  ld.** using sqli
59f0: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
5a00: 29 20 75 70 6f 6e 20 66 69 72 73 74 20 75 73 65  ) upon first use
5a10: 20 6f 66 20 74 68 65 20 61 64 61 70 74 6f 72 0a   of the adaptor.
5a20: 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6f 70  ** by sqlite3_op
5a30: 65 6e 5f 76 32 28 29 20 61 6e 64 20 77 69 6c 6c  en_v2() and will
5a40: 20 64 65 61 6c 6c 6f 63 61 74 65 20 74 68 65 20   deallocate the 
5a50: 6d 75 74 65 78 20 77 68 65 6e 20 74 68 65 0a 2a  mutex when the.*
5a60: 2a 20 6c 61 73 74 20 75 73 65 72 20 63 6c 6f 73  * last user clos
5a70: 65 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  es.  In other wo
5a80: 72 64 73 2c 20 76 66 73 4d 75 74 65 78 20 77 69  rds, vfsMutex wi
5a90: 6c 6c 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a  ll be allocated.
5aa0: 2a 2a 20 77 68 65 6e 20 6e 52 65 66 20 74 72 61  ** when nRef tra
5ab0: 6e 73 69 74 69 6f 6e 73 20 66 72 6f 6d 20 30 20  nsitions from 0 
5ac0: 74 6f 20 31 20 61 6e 64 20 77 69 6c 6c 20 62 65  to 1 and will be
5ad0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65   deallocated whe
5ae0: 6e 0a 2a 2a 20 6e 52 65 66 20 74 72 61 6e 73 69  n.** nRef transi
5af0: 74 69 6f 6e 73 20 66 72 6f 6d 20 31 20 74 6f 20  tions from 1 to 
5b00: 30 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  0..**.** Registe
5b10: 72 65 64 20 76 66 73 20 6d 6f 64 75 6c 65 73 20  red vfs modules 
5b20: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
5b30: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
5b40: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
5b50: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
5b60: 73 71 6c 69 74 65 33 5f 72 65 67 69 73 74 65 72  sqlite3_register
5b70: 5f 76 66 73 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  _vfs()].** and [
5b80: 73 71 6c 69 74 65 33 5f 75 6e 72 65 67 69 73 74  sqlite3_unregist
5b90: 65 72 5f 76 66 73 28 29 5d 20 69 6e 74 65 72 66  er_vfs()] interf
5ba0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
5bb0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
5bc0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
5bd0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  The [sqlite3_fin
5be0: 64 5f 76 66 73 28 29 5d 20 69 6e 74 65 72 66 61  d_vfs()] interfa
5bf0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
5c00: 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  he list..**.** T
5c10: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
5c20: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
5c30: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
5c40: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
5c50: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
5c60: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
5c70: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  les..**.** SQLit
5c80: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
5c90: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
5ca0: 61 6d 65 20 73 74 72 69 6e 67 20 70 61 73 73 65  ame string passe
5cb0: 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20  d to.** xOpen() 
5cc0: 69 73 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61  is a full pathna
5cd0: 6d 65 20 61 73 20 67 65 6e 65 72 61 74 65 64 20  me as generated 
5ce0: 62 79 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  by xFullPathname
5cf0: 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74  () and.** that t
5d00: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
5d10: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
5d20: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
5d30: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
5d40: 64 2e 20 20 53 6f 20 74 68 65 20 73 71 6c 69 74  d.  So the sqlit
5d50: 65 33 5f 66 69 6c 65 20 63 61 6e 20 73 74 6f 72  e3_file can stor
5d60: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
5d70: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
5d80: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
5d90: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
5da0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
5db0: 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  son..**.** The f
5dc0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
5dd0: 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20 63 6f   xOpen() is a co
5de0: 70 79 20 6f 66 20 74 68 65 20 66 6c 61 67 73 20  py of the flags 
5df0: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
5e00: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e10: 2e 20 20 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  .  If sqlite3_op
5e20: 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
5e30: 6f 70 65 6e 31 36 28 29 0a 2a 2a 20 69 73 20 75  open16().** is u
5e40: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
5e50: 69 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  is SQLITE_OPEN_R
5e60: 45 41 44 57 52 49 54 45 20 7c 20 53 51 4c 49 54  EADWRITE | SQLIT
5e70: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 0a 2a  E_OPEN_CREATE..*
5e80: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
5e90: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
5ea0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
5eb0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
5ec0: 2a 20 69 6e 63 6c 75 64 65 20 53 51 4c 49 54 45  * include SQLITE
5ed0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 2e 20  _OPEN_READONLY. 
5ee0: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
5ef0: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
5f00: 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20  .** set..** .** 
5f10: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
5f20: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
5f30: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
5f40: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
5f50: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
5f60: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
5f70: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
5f80: 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69   .** <ul>.** <li
5f90: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
5fa0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
5fb0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
5fc0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
5fd0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
5fe0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
5ff0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
6000: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
6010: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
6020: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
6030: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
6040: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
6050: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  OURNAL].** </ul>
6060: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
6070: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
6080: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
6090: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
60a0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74   to.** changes t
60b0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
60c0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
60d0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
60e0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
60f0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
6100: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
6110: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 2c  ery or rollback,
6120: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
6130: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
6140: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
6150: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
6160: 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72 65 0a 2a  is journal are.*
6170: 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e 20  * also a no-op. 
6180: 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
6190: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
61a0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 49   return SQLITE_I
61b0: 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 68 65 20  OERR..** Or the 
61c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
61d0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
61e0: 68 65 20 61 20 64 61 74 61 62 61 73 65 20 66 69  he a database fi
61f0: 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 64 6f  le will.** be do
6200: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
6210: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
6220: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
6230: 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20 61 6e  ndom order.** an
6240: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
6250: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
6260: 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53  dingly..** .** S
6270: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
6280: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
6290: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
62a0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
62b0: 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  method:.** .** <
62c0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
62d0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
62e0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
62f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
6300: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
6310: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  .** .** The [SQL
6320: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
6330: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
6340: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
6350: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
6360: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
6370: 65 64 2e 20 20 54 68 69 73 20 77 69 6c 6c 20 61  ed.  This will a
6380: 6c 77 61 79 73 20 62 65 20 73 65 74 20 66 6f 72  lways be set for
6390: 20 54 45 4d 50 20 0a 2a 2a 20 64 61 74 61 62 61   TEMP .** databa
63a0: 73 65 73 20 61 6e 64 20 6a 6f 75 72 6e 61 6c 73  ses and journals
63b0: 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72   and for subjour
63c0: 6e 61 6c 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b  nals.  The .** [
63d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
63e0: 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e  USIVE] flag mean
63f0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
6400: 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66  d be opened.** f
6410: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
6420: 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20  ess.  This flag 
6430: 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66  is set for all f
6440: 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66  iles except.** f
6450: 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
6460: 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 0a 2a  base file..** .*
6470: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69  * The sqlite3_fi
6480: 6c 65 20 73 74 72 75 63 74 75 72 65 20 70 61 73  le structure pas
6490: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
64a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
64b0: 78 4f 70 65 6e 20 69 73 20 61 6c 6c 6f 63 61 74  xOpen is allocat
64c0: 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ed by the caller
64d0: 2e 20 20 78 4f 70 65 6e 20 6a 75 73 74 20 66 69  .  xOpen just fi
64e0: 6c 6c 73 20 69 74 20 69 6e 2e 20 20 54 68 65 0a  lls it in.  The.
64f0: 2a 2a 20 63 61 6c 6c 65 72 20 61 6c 6c 6f 63 61  ** caller alloca
6500: 74 65 73 20 61 20 6d 69 6e 69 6d 75 6d 20 6f 66  tes a minimum of
6510: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
6520: 66 6f 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  for the sqlite3_
6530: 66 69 6c 65 0a 2a 2a 20 73 74 72 75 63 74 75 72  file.** structur
6540: 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 66 6c  e..** .** The fl
6550: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
6560: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
6570: 20 30 20 28 74 6f 20 74 65 73 74 20 66 6f 72 20   0 (to test for 
6580: 74 68 65 0a 2a 2a 20 65 78 69 73 74 61 6e 63 65  the.** existance
6590: 20 6f 66 20 61 20 66 69 6c 65 29 20 6f 72 20 53   of a file) or S
65a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
65b0: 44 57 52 49 54 45 20 74 6f 20 74 65 73 74 20 74  DWRITE to test t
65c0: 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61 20 66 69  o see.** if a fi
65d0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
65e0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
65f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
6600: 41 44 4f 4e 4c 59 0a 2a 2a 20 74 6f 20 74 65 73  ADONLY.** to tes
6610: 74 20 74 6f 20 73 65 65 20 69 66 20 61 20 66 69  t to see if a fi
6620: 6c 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2e  le is read-only.
6630: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
6640: 65 20 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f 72  e a .** director
6650: 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65  y..** .** SQLite
6660: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
6670: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
6680: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
6690: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74 70   for.** the outp
66a0: 75 74 20 62 75 66 66 65 72 73 20 66 6f 72 20 78  ut buffers for x
66b0: 47 65 74 54 65 6d 70 4e 61 6d 65 20 61 6e 64 20  GetTempName and 
66c0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 0a 2a  xFullPathname..*
66d0: 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  * .** The xRando
66e0: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
66f0: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
6700: 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  ime() interfaces
6710: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69  .** are not stri
6720: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
6730: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
6740: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
6750: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
6760: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
6770: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
6780: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
6790: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
67a0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
67b0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
67c0: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
67d0: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
67e0: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
67f0: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
6800: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
6810: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
6820: 6f 6d 6e 65 73 73 20 67 65 6e 65 72 61 74 65 64  omness generated
6830: 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c 65 65 70  .  The.** xSleep
6840: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 20  () method cause 
6850: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
6860: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
6870: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
6880: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
6890: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54  econds given.  T
68a0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
68b0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
68c0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
68d0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
68e0: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
68f0: 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70  .** time..*/.typ
6900: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
6910: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
6920: 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  vfs;.struct sqli
6930: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
6940: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
6950: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
6960: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
6970: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
6980: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
6990: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
69a0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
69b0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
69c0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
69d0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
69e0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
69f0: 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20  */.  int nRef;  
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
6a10: 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 66 65 72   Number of refer
6a20: 65 6e 63 65 73 20 74 6f 20 74 68 69 73 20 73 74  ences to this st
6a30: 72 75 63 74 75 72 65 20 2a 2f 0a 20 20 73 71 6c  ructure */.  sql
6a40: 69 74 65 33 5f 6d 75 74 65 78 20 2a 76 66 73 4d  ite3_mutex *vfsM
6a50: 75 74 65 78 3b 20 2f 2a 20 41 20 6d 75 74 65 78  utex; /* A mutex
6a60: 20 66 6f 72 20 74 68 69 73 20 56 46 53 20 2a 2f   for this VFS */
6a70: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
6a80: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
6a90: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
6aa0: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
6ab0: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
6ac0: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
6ad0: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
6ae0: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
6af0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
6b00: 20 20 20 2f 2a 20 41 70 70 6c 69 63 61 74 69 6f     /* Applicatio
6b10: 6e 20 63 6f 6e 74 65 78 74 20 2a 2f 0a 20 20 69  n context */.  i
6b20: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
6b30: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
6b40: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
6b50: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
6b60: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
6b70: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
6b80: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
6b90: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
6ba0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
6bb0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
6bc0: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
6bd0: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
6be0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
6bf0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
6c00: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  gs);.  int (*xGe
6c10: 74 54 65 6d 70 4e 61 6d 65 29 28 73 71 6c 69 74  tTempName)(sqlit
6c20: 65 33 5f 76 66 73 2a 2c 20 63 68 61 72 20 2a 7a  e3_vfs*, char *z
6c30: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
6c40: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
6c50: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
6c60: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 63 68   char *zName, ch
6c70: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
6c80: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
6c90: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
6ca0: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
6cb0: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
6cc0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
6cd0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
6ce0: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
6cf0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d    void *(*xDlSym
6d00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
6d10: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
6d20: 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f   *zSymbol);.  vo
6d30: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
6d40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
6d50: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
6d60: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
6d70: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
6d80: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
6d90: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
6da0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
6db0: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
6dc0: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
6dd0: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
6de0: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
6df0: 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   /* New fields m
6e00: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
6e10: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
6e20: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
6e30: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
6e40: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
6e50: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
6e60: 2e 20 2a 2f 0a 7d 3b 0a 0a 23 64 65 66 69 6e 65  . */.};..#define
6e70: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
6e80: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
6e90: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
6ea0: 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65  _READWRITE 1.#de
6eb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
6ec0: 53 53 5f 52 45 41 44 4f 4e 4c 59 20 20 32 0a 0a  SS_READONLY  2..
6ed0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6ee0: 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
6ef0: 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
6f00: 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  t Codes.**.** Th
6f10: 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
6f20: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
6f30: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  he.** [SQLITE_IO
6f40: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
6f50: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
6f60: 5d 20 66 65 61 74 75 72 65 2e 0a 2a 2a 20 42 79  ] feature..** By
6f70: 20 64 65 66 61 75 6c 74 2c 20 53 51 4c 69 74 65   default, SQLite
6f80: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
6f90: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 6f 6e 6c 79  turn one of only
6fa0: 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   26 integer.** [
6fb0: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
6fc0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 57 68 65 6e  lt codes].  When
6fd0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
6fe0: 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20 65 6e   codes.** are en
6ff0: 61 62 6c 65 64 20 62 79 20 74 68 69 73 20 72 6f  abled by this ro
7000: 75 74 69 6e 65 2c 20 74 68 65 20 72 65 70 65 74  utine, the repet
7010: 6f 69 72 65 20 6f 66 20 72 65 73 75 6c 74 20 63  oire of result c
7020: 6f 64 65 73 20 63 61 6e 20 62 65 0a 2a 2a 20 6d  odes can be.** m
7030: 75 63 68 20 6c 61 72 67 65 72 20 61 6e 64 20 63  uch larger and c
7040: 61 6e 20 28 68 6f 70 65 66 75 6c 6c 79 29 20 70  an (hopefully) p
7050: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
7060: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
7070: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 63 61  .** about the ca
7080: 75 73 65 20 6f 66 20 61 6e 20 65 72 72 6f 72 2e  use of an error.
7090: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
70a0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
70b0: 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65 20 74 68  boolean value th
70c0: 61 74 20 74 75 72 6e 73 20 65 78 74 65 6e 64 65  at turns extende
70d0: 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
70e0: 73 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 20 20 45  s on and off.  E
70f0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
7100: 6f 64 65 73 20 61 72 65 20 6f 66 66 20 62 79 20  odes are off by 
7110: 64 65 66 61 75 6c 74 20 66 6f 72 0a 2a 2a 20 62  default for.** b
7120: 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
7130: 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
7140: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
7150: 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
7160: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
7170: 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
7180: 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
7190: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
71a0: 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
71b0: 77 69 64 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65  wid.**.** Each e
71c0: 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74  ntry in an SQLit
71d0: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e  e table has a un
71e0: 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
71f0: 65 64 20 69 6e 74 65 67 65 72 20 6b 65 79 0a 2a  ed integer key.*
7200: 2a 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f  * called the "ro
7210: 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20  wid". The rowid 
7220: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
7230: 62 6c 65 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  ble as an undecl
7240: 61 72 65 64 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e  ared.** column n
7250: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
7260: 20 6f 72 20 5f 52 4f 57 49 44 5f 2e 20 20 49 66   or _ROWID_.  If
7270: 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
7280: 20 63 6f 6c 75 6d 6e 20 6f 66 0a 2a 2a 20 74 79   column of.** ty
7290: 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  pe INTEGER PRIMA
72a0: 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74  RY KEY then that
72b0: 20 63 6f 6c 75 6d 6e 20 69 73 20 61 6e 6f 74 68   column is anoth
72c0: 65 72 20 61 6e 20 61 6c 69 61 73 20 66 6f 72 20  er an alias for 
72d0: 74 68 65 0a 2a 2a 20 72 6f 77 69 64 2e 0a 2a 2a  the.** rowid..**
72e0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
72f0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77   returns the row
7300: 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  id of the most r
7310: 65 63 65 6e 74 20 49 4e 53 45 52 54 20 69 6e 74  ecent INSERT int
7320: 6f 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  o.** the databas
7330: 65 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62  e from the datab
7340: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 67  ase connection g
7350: 69 76 65 6e 20 69 6e 20 74 68 65 20 66 69 72 73  iven in the firs
7360: 74 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  t .** argument. 
7370: 20 49 66 20 6e 6f 20 69 6e 73 65 72 74 73 20 68   If no inserts h
7380: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
7390: 64 20 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61  d on this databa
73a0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
73b0: 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
73c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
73d0: 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77 69  INSERT occurs wi
73e0: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
73f0: 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f  then the rowid o
7400: 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65  f the.** inserte
7410: 64 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65  d row is returne
7420: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
7430: 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  e as long as the
7440: 20 74 72 69 67 67 65 72 0a 2a 2a 20 69 73 20 72   trigger.** is r
7450: 75 6e 6e 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63  unning.  But onc
7460: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
7470: 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
7480: 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
7490: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
74a0: 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
74b0: 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
74c0: 65 64 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a  ed before the.**
74d0: 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a   trigger fired..
74e0: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
74f0: 20 74 68 72 65 61 64 20 64 6f 65 73 20 61 20 6e   thread does a n
7500: 65 77 20 69 6e 73 65 72 74 20 6f 6e 20 74 68 65  ew insert on the
7510: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
7520: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
7530: 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
7540: 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
7550: 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
7560: 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69  last insert rowi
7570: 64 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  d,.** then the r
7580: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
7590: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
75a0: 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 73 71 6c  ndefined..*/.sql
75b0: 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
75c0: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
75d0: 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
75e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
75f0: 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
7600: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
7610: 65 64 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  ed.**.** This fu
7620: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
7630: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
7640: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
7650: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
7660: 28 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20  (or inserted or 
7670: 64 65 6c 65 74 65 64 29 20 62 79 20 74 68 65 20  deleted) by the 
7680: 6d 6f 73 74 20 72 65 63 65 6e 74 20 53 51 4c 20  most recent SQL 
7690: 73 74 61 74 65 6d 65 6e 74 2e 20 20 4f 6e 6c 79  statement.  Only
76a0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68 61 74  .** changes that
76b0: 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
76c0: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49  ecified by the I
76d0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
76e0: 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74  r.** DELETE stat
76f0: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
7700: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
7710: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
7720: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
7730: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 55 73  not counted.  Us
7740: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
7750: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
7760: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66  function.** to f
7770: 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
7780: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
7790: 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
77a0: 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
77b0: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 57 69 74 68  gers..**.** With
77c0: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
77d0: 20 74 72 69 67 67 65 72 2c 20 74 68 65 20 73 71   trigger, the sq
77e0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
77f0: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
7800: 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 6f 20 66 69  .** called to fi
7810: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
7820: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
7830: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
7840: 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
7850: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
7860: 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
7870: 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
7880: 79 20 6f 66 20 74 68 65 20 74 72 69 67 67 65 72  y of the trigger
7890: 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 63 68 61 6e  ..**.** All chan
78a0: 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2c  ges are counted,
78b0: 20 65 76 65 6e 20 69 66 20 74 68 65 79 20 77 65   even if they we
78c0: 72 65 20 6c 61 74 65 72 20 75 6e 64 6f 6e 65 20  re later undone 
78d0: 62 79 20 61 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b  by a.** ROLLBACK
78e0: 20 6f 72 20 41 42 4f 52 54 2e 20 20 45 78 63 65   or ABORT.  Exce
78f0: 70 74 2c 20 63 68 61 6e 67 65 73 20 61 73 73 6f  pt, changes asso
7900: 63 69 61 74 65 64 20 77 69 74 68 20 63 72 65 61  ciated with crea
7910: 74 69 6e 67 20 61 6e 64 0a 2a 2a 20 64 72 6f 70  ting and.** drop
7920: 70 69 6e 67 20 74 61 62 6c 65 73 20 61 72 65 20  ping tables are 
7930: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  not counted..**.
7940: 2a 2a 20 49 66 20 61 20 63 61 6c 6c 62 61 63 6b  ** If a callback
7950: 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
7960: 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
7970: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
7980: 63 75 72 73 69 76 65 6c 79 2c 0a 2a 2a 20 74 68  cursively,.** th
7990: 65 6e 20 74 68 65 20 63 68 61 6e 67 65 73 20 69  en the changes i
79a0: 6e 20 74 68 65 20 69 6e 6e 65 72 2c 20 72 65 63  n the inner, rec
79b0: 75 72 73 69 76 65 20 63 61 6c 6c 20 61 72 65 20  ursive call are 
79c0: 63 6f 75 6e 74 65 64 20 74 6f 67 65 74 68 65 72  counted together
79d0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 63 68 61  .** with the cha
79e0: 6e 67 65 73 20 69 6e 20 74 68 65 20 6f 75 74 65  nges in the oute
79f0: 72 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 53 51  r call..**.** SQ
7a00: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
7a10: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
7a20: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
7a30: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
7a40: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
7a50: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
7a60: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
7a70: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
7a80: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
7a90: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
7aa0: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
7ab0: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
7ac0: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
7ad0: 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69  ecause of.** thi
7ae0: 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  s optimization, 
7af0: 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74  the change count
7b00: 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f   for "DELETE FRO
7b10: 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65  M table" will be
7b20: 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c  .** zero regardl
7b30: 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ess of the numbe
7b40: 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68  r of elements th
7b50: 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c  at were original
7b60: 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62  ly in the.** tab
7b70: 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63  le. To get an ac
7b80: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
7b90: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
7ba0: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
7bb0: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
7bc0: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
7bd0: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  nstead..**.** If
7be0: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
7bf0: 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
7c00: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
7c10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
7c20: 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
7c30: 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ine is running t
7c40: 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
7c50: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75  alue of this rou
7c60: 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  tine.** is undef
7c70: 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
7c80: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
7c90: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
7ca0: 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
7cb0: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
7cc0: 64 69 66 69 65 64 0a 2a 2a 2a 0a 2a 2a 20 54 68  dified.***.** Th
7cd0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
7ce0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
7cf0: 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
7d00: 74 68 61 74 20 68 61 76 65 20 62 65 65 6e 0a 2a  that have been.*
7d10: 2a 20 6d 6f 64 69 66 69 65 64 20 62 79 20 49 4e  * modified by IN
7d20: 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
7d30: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
7d40: 73 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  s since the data
7d50: 62 61 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77  base handle.** w
7d60: 61 73 20 6f 70 65 6e 65 64 2e 20 54 68 69 73 20  as opened. This 
7d70: 69 6e 63 6c 75 64 65 73 20 55 50 44 41 54 45 2c  includes UPDATE,
7d80: 20 49 4e 53 45 52 54 20 61 6e 64 20 44 45 4c 45   INSERT and DELE
7d90: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 65 78  TE statements ex
7da0: 65 63 75 74 65 64 0a 2a 2a 20 61 73 20 70 61 72  ecuted.** as par
7db0: 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
7dc0: 67 72 61 6d 73 2e 20 41 6c 6c 20 63 68 61 6e 67  grams. All chang
7dd0: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  es are counted a
7de0: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 0a 2a 2a  s soon as the.**
7df0: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
7e00: 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
7e10: 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
7e20: 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
7e30: 6c 65 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  le is.** passed 
7e40: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
7e50: 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
7e60: 5f 66 69 6e 61 6c 69 73 65 28 29 5d 29 2e 0a 2a  _finalise()])..*
7e70: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
7e80: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
7e90: 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  e()] interface..
7ea0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
7eb0: 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d  lements the comm
7ec0: 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  and "DELETE FROM
7ed0: 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20   table" without 
7ee0: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a  a WHERE clause.*
7ef0: 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e  * by dropping an
7f00: 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65  d recreating the
7f10: 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69   table.  (This i
7f20: 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68  s much faster th
7f30: 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f  an going.** thro
7f40: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
7f50: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
7f60: 65 6e 74 73 20 66 6f 72 6d 20 74 68 65 20 74 61  ents form the ta
7f70: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
7f80: 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69  f.** this optimi
7f90: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e  zation, the chan
7fa0: 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45  ge count for "DE
7fb0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
7fc0: 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f   will be.** zero
7fd0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
7fe0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
7ff0: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
8000: 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68  originally in th
8010: 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67  e.** table. To g
8020: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
8030: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
8040: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
8050: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
8060: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
8070: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a  ERE 1" instead..
8080: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
8090: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
80a0: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
80b0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
80c0: 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74  ction.** while t
80d0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
80e0: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
80f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
8100: 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
8110: 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
8120: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
8130: 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
8140: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
8150: 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
8160: 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
8170: 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73  Query.**.** This
8180: 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
8190: 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
81a0: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
81b0: 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
81c0: 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
81d0: 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
81e0: 74 79 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  ty.  This routin
81f0: 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
8200: 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
8210: 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
8220: 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
8230: 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
8240: 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
8250: 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
8260: 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
8270: 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
8280: 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
8290: 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66  .**.** It is saf
82a0: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
82b0: 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
82c0: 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
82d0: 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
82e0: 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
82f0: 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
8300: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
8310: 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
8320: 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
8330: 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
8340: 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
8350: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 0a  connection that.
8360: 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
8370: 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
8380: 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
8390: 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
83a0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 20 6f 70  **.** The SQL op
83b0: 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
83c0: 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
83d0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
83e0: 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49  INTERRUPT]..** I
83f0: 66 20 61 6e 20 69 6e 74 65 72 72 75 70 74 65 64  f an interrupted
8400: 20 6f 70 65 72 61 74 69 6f 6e 20 77 61 73 20 61   operation was a
8410: 6e 20 75 70 64 61 74 65 20 74 68 61 74 20 69 73  n update that is
8420: 20 69 6e 73 69 64 65 20 61 6e 0a 2a 2a 20 65 78   inside an.** ex
8430: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
8440: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
8450: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ire transaction 
8460: 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 0a 2a  will be rolled.*
8470: 2a 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  * back automatic
8480: 61 6c 6c 79 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ally..*/.void sq
8490: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
84a0: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
84b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
84c0: 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
84d0: 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
84e0: 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
84f0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
8500: 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 67  rn true if the g
8510: 69 76 65 6e 20 69 6e 70 75 74 20 73 74 72 69 6e  iven input strin
8520: 67 20 63 6f 6d 70 72 69 73 65 73 0a 2a 2a 20 6f  g comprises.** o
8530: 6e 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c  ne or more compl
8540: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
8550: 74 73 2e 20 46 6f 72 20 74 68 65 20 73 71 6c 69  ts. For the sqli
8560: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 63  te3_complete() c
8570: 61 6c 6c 2c 0a 2a 2a 20 74 68 65 20 70 61 72 61  all,.** the para
8580: 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
8590: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  nul-terminated U
85a0: 54 46 2d 38 20 73 74 72 69 6e 67 2e 20 46 6f 72  TF-8 string. For
85b0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
85c0: 6c 65 74 65 31 36 28 29 2c 20 61 20 6e 75 6c 2d  lete16(), a nul-
85d0: 74 65 72 6d 69 6e 61 74 65 64 20 6d 61 63 68 69  terminated machi
85e0: 6e 65 20 62 79 74 65 20 6f 72 64 65 72 20 55 54  ne byte order UT
85f0: 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
8600: 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
8610: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
8620: 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
8630: 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
8640: 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
8650: 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
8660: 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
8670: 20 66 6f 72 6d 73 20 6f 6e 65 20 6f 72 20 6d 6f   forms one or mo
8680: 72 65 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20  re complete SQL 
8690: 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 0a 2a 2a  statements or.**
86a0: 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
86b0: 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
86c0: 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
86d0: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 74  e statements int
86e0: 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
86f0: 70 61 72 73 69 6e 67 2e 20 54 68 65 20 61 6c 67  parsing. The alg
8700: 6f 72 69 74 68 6d 20 69 73 20 73 69 6d 70 6c 65  orithm is simple
8710: 2e 20 20 49 66 20 74 68 65 20 0a 2a 2a 20 6c 61  .  If the .** la
8720: 73 74 20 74 6f 6b 65 6e 20 6f 74 68 65 72 20 74  st token other t
8730: 68 61 6e 20 73 70 61 63 65 73 20 61 6e 64 20 63  han spaces and c
8740: 6f 6d 6d 65 6e 74 73 20 69 73 20 61 20 73 65 6d  omments is a sem
8750: 69 63 6f 6c 6f 6e 2c 20 74 68 65 6e 20 72 65 74  icolon, then ret
8760: 75 72 6e 20 0a 2a 2a 20 74 72 75 65 2e 20 20 41  urn .** true.  A
8770: 63 74 75 61 6c 6c 79 2c 20 74 68 65 20 61 6c 67  ctually, the alg
8780: 6f 72 69 74 68 6d 20 69 73 20 61 20 6c 69 74 74  orithm is a litt
8790: 6c 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  le more complica
87a0: 74 65 64 20 74 68 61 6e 20 74 68 61 74 0a 2a 2a  ted than that.**
87b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 61   in order to dea
87c0: 6c 20 77 69 74 68 20 74 72 69 67 67 65 72 73 2c  l with triggers,
87d0: 20 62 75 74 20 74 68 65 20 62 61 73 69 63 20 69   but the basic i
87e0: 64 65 61 20 69 73 20 74 68 65 20 73 61 6d 65 3a  dea is the same:
87f0: 20 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65    the.** stateme
8800: 6e 74 20 69 73 20 6e 6f 74 20 63 6f 6d 70 6c 65  nt is not comple
8810: 74 65 20 75 6e 6c 65 73 73 20 69 74 20 65 6e 64  te unless it end
8820: 73 20 69 6e 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  s in a semicolon
8830: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
8840: 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
8850: 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
8860: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
8870: 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
8880: 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
8890: 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
88a0: 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
88b0: 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
88c0: 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69  Errors.**.** Thi
88d0: 73 20 72 6f 75 74 69 6e 65 20 69 64 65 6e 74 69  s routine identi
88e0: 66 69 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  fies a callback 
88f0: 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
8900: 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ght be invoked.*
8910: 2a 20 77 68 65 6e 65 76 65 72 20 61 6e 20 61 74  * whenever an at
8920: 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
8930: 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
8940: 20 74 61 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20   table .** that 
8950: 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6f  another thread o
8960: 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
8970: 63 6b 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cked..** If the 
8980: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
8990: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
89a0: 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 28 6f 72  ITE_BUSY].** (or
89b0: 20 73 6f 6d 65 74 69 6d 65 73 20 5b 53 51 4c 49   sometimes [SQLI
89c0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
89d0: 5d 29 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ]).** is returne
89e0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
89f0: 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
8a00: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20  the lock..** If 
8a10: 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
8a20: 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  k is not NULL, t
8a30: 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62  hen the.** callb
8a40: 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  ack will be invo
8a50: 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
8a60: 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20  uments.  The.** 
8a70: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
8a80: 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73  o the handler is
8a90: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
8aa0: 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
8ab0: 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
8ac0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
8ad0: 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  his routine.  Th
8ae0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
8af0: 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64  t to.** the hand
8b00: 6c 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ler is the numbe
8b10: 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
8b20: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
8b30: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
8b40: 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
8b50: 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 49 66 20  cking event. If 
8b60: 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
8b70: 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
8b80: 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
8b90: 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
8ba0: 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
8bb0: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
8bc0: 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
8bd0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
8be0: 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
8bf0: 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68  turned..** If th
8c00: 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
8c10: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
8c20: 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
8c30: 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
8c40: 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
8c50: 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
8c60: 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
8c70: 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
8c80: 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
8c90: 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
8ca0: 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
8cb0: 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62 65 20  t.** it will be 
8cc0: 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
8cd0: 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
8ce0: 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c  ntion..** If SQL
8cf0: 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
8d00: 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
8d10: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6f   busy handler co
8d20: 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a  uld result in.**
8d30: 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
8d40: 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
8d50: 49 54 45 5f 42 55 53 59 5d 20 69 6e 73 74 65 61  ITE_BUSY] instea
8d60: 64 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  d..** Consider a
8d70: 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
8d80: 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
8d90: 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
8da0: 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
8db0: 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
8dc0: 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
8dd0: 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
8de0: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
8df0: 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
8e00: 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
8e10: 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
8e20: 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
8e30: 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
8e40: 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
8e50: 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
8e60: 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
8e70: 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
8e80: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
8e90: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
8ea0: 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
8eb0: 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
8ec0: 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
8ed0: 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
8ee0: 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
8ef0: 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
8f00: 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
8f10: 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
8f20: 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
8f30: 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
8f40: 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
8f50: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
8f60: 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
8f70: 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
8f80: 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
8f90: 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
8fa0: 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
8fb0: 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
8fc0: 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
8fd0: 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
8fe0: 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
8ff0: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
9000: 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
9010: 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
9020: 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
9030: 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
9040: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 77 68 65  ERR_BLOCKED] whe
9050: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 69  n.** SQLite is i
9060: 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
9070: 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
9080: 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
9090: 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
90a0: 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
90b0: 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
90c0: 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
90d0: 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
90e0: 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
90f0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
9100: 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
9110: 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
9120: 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
9130: 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
9140: 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
9150: 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
9160: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
9170: 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
9180: 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
9190: 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69  * readers.  If i
91a0: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
91b0: 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
91c0: 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
91d0: 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
91e0: 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
91f0: 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
9200: 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
9210: 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
9220: 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
9230: 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
9240: 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
9250: 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
9260: 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
9270: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
9280: 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
9290: 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
92a0: 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
92b0: 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
92c0: 20 63 68 61 6e 67 65 73 2e 20 53 65 65 20 74 68   changes. See th
92d0: 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74  e.** <a href="ht
92e0: 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e  tp://www.sqlite.
92f0: 6f 72 67 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  org/cvstrac/wiki
9300: 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
9310: 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
9320: 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
9330: 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
9340: 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
9350: 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
9360: 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
9370: 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
9380: 09 0a 2a 2a 20 53 71 6c 69 74 65 20 69 73 20 72  ..** Sqlite is r
9390: 65 2d 65 6e 74 72 61 6e 74 2c 20 73 6f 20 74 68  e-entrant, so th
93a0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  e busy handler m
93b0: 61 79 20 73 74 61 72 74 20 61 20 6e 65 77 20 71  ay start a new q
93c0: 75 65 72 79 2e 20 0a 2a 2a 20 28 49 74 20 69 73  uery. .** (It is
93d0: 20 6e 6f 74 20 63 6c 65 61 72 20 77 68 79 20 61   not clear why a
93e0: 6e 79 6f 6e 65 20 77 6f 75 6c 64 20 65 76 65 72  nyone would ever
93f0: 79 20 77 61 6e 74 20 74 6f 20 64 6f 20 74 68 69  y want to do thi
9400: 73 2c 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  s, but it.** is 
9410: 61 6c 6c 6f 77 65 64 2c 20 69 6e 20 74 68 65 6f  allowed, in theo
9420: 72 79 2e 29 20 20 42 75 74 20 74 68 65 20 62 75  ry.)  But the bu
9430: 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 6e  sy handler may n
9440: 6f 74 20 63 6c 6f 73 65 20 74 68 65 0a 2a 2a 20  ot close the.** 
9450: 64 61 74 61 62 61 73 65 2e 20 20 43 6c 6f 73 69  database.  Closi
9460: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
9470: 66 72 6f 6d 20 61 20 62 75 73 79 20 68 61 6e 64  from a busy hand
9480: 6c 65 72 20 77 69 6c 6c 20 64 65 6c 65 74 65 20  ler will delete 
9490: 0a 2a 2a 20 64 61 74 61 20 73 74 72 75 63 74 75  .** data structu
94a0: 72 65 73 20 6f 75 74 20 66 72 6f 6d 20 75 6e 64  res out from und
94b0: 65 72 20 74 68 65 20 65 78 65 63 75 74 69 6e 67  er the executing
94c0: 20 71 75 65 72 79 20 61 6e 64 20 77 69 6c 6c 20   query and will 
94d0: 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 73  .** probably res
94e0: 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
94f0: 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
9500: 74 68 65 72 20 72 75 6e 74 69 6d 65 20 65 72 72  ther runtime err
9510: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  or..**.** There 
9520: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
9530: 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
9540: 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
9550: 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ch database.** c
9560: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 74  onnection.  Sett
9570: 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
9580: 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
9590: 79 20 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e 0a  y previous one..
95a0: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c  ** Note that cal
95b0: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
95c0: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 69  sy_timeout()] wi
95d0: 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
95e0: 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 79  lear.** the busy
95f0: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
9600: 57 68 65 6e 20 6f 70 65 72 61 74 69 6e 67 20 69  When operating i
9610: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  n [sqlite3_enabl
9620: 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c  e_shared_cache |
9630: 20 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f   shared cache mo
9640: 64 65 5d 2c 0a 2a 2a 20 6f 6e 6c 79 20 61 20 73  de],.** only a s
9650: 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
9660: 65 72 20 63 61 6e 20 62 65 20 64 65 66 69 6e 65  er can be define
9670: 64 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62  d for each datab
9680: 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 53 6f 20  ase file..** So 
9690: 69 66 20 74 77 6f 20 64 61 74 61 62 61 73 65 20  if two database 
96a0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 73 68 61 72  connections shar
96b0: 65 20 61 20 73 69 6e 67 6c 65 20 63 61 63 68 65  e a single cache
96c0: 2c 20 74 68 65 6e 20 63 68 61 6e 67 69 6e 67 0a  , then changing.
96d0: 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
96e0: 6c 65 72 20 6f 6e 20 6f 6e 65 20 63 6f 6e 6e 65  ler on one conne
96f0: 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 73 6f 20  ction will also 
9700: 63 68 61 6e 67 65 20 74 68 65 20 62 75 73 79 0a  change the busy.
9710: 2a 2a 20 68 61 6e 64 6c 65 72 20 69 6e 20 74 68  ** handler in th
9720: 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69  e other connecti
9730: 6f 6e 2e 20 20 54 68 65 20 62 75 73 79 20 68 61  on.  The busy ha
9740: 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  ndler is invoked
9750: 0a 2a 2a 20 69 6e 20 74 68 65 20 74 68 72 65 61  .** in the threa
9760: 64 20 74 68 61 74 20 77 61 73 20 72 75 6e 6e 69  d that was runni
9770: 6e 67 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49  ng when the SQLI
9780: 54 45 5f 42 55 53 59 20 77 61 73 20 68 69 74 2e  TE_BUSY was hit.
9790: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
97a0: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
97b0: 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
97c0: 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
97d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
97e0: 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
97f0: 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 54 68 69 73  meout.**.** This
9800: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
9810: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 74 68 61  busy handler tha
9820: 74 20 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77  t sleeps for a w
9830: 68 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74  hile when a.** t
9840: 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
9850: 20 54 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c   The handler wil
9860: 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
9870: 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a   times until .**
9880: 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
9890: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
98a0: 6c 65 65 70 69 6e 67 20 68 61 76 65 20 62 65 65  leeping have bee
98b0: 6e 20 64 6f 6e 65 2e 20 20 41 66 74 65 72 0a 2a  n done.  After.*
98c0: 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  * "ms" milliseco
98d0: 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
98e0: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
98f0: 75 72 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a 20  urns 0 which.** 
9900: 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
9910: 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
9920: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
9930: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
9940: 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
9950: 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
9960: 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
9970: 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
9980: 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
9990: 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
99a0: 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
99b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
99c0: 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
99d0: 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
99e0: 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
99f0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9a00: 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f  nection.  If ano
9a10: 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
9a20: 72 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 0a  r was defined  .
9a30: 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  ** (using [sqlit
9a40: 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
9a50: 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
9a60: 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
9a70: 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
9a80: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
9a90: 20 63 6c 65 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74   cleared..*/.int
9aa0: 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
9ab0: 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
9ac0: 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
9ad0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
9ae0: 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
9af0: 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
9b00: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6e 65  es.**.** This ne
9b10: 78 74 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  xt routine is a 
9b20: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70  convenience wrap
9b30: 70 65 72 20 61 72 6f 75 6e 64 20 5b 73 71 6c 69  per around [sqli
9b40: 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2a 20  te3_exec()]..** 
9b50: 49 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  Instead of invok
9b60: 69 6e 67 20 61 20 75 73 65 72 2d 73 75 70 70 6c  ing a user-suppl
9b70: 69 65 64 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  ied callback for
9b80: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65   each row of the
9b90: 0a 2a 2a 20 72 65 73 75 6c 74 2c 20 74 68 69 73  .** result, this
9ba0: 20 72 6f 75 74 69 6e 65 20 72 65 6d 65 6d 62 65   routine remembe
9bb0: 72 73 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74  rs each row of t
9bc0: 68 65 20 72 65 73 75 6c 74 20 69 6e 20 6d 65 6d  he result in mem
9bd0: 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ory.** obtained 
9be0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
9bf0: 6c 6c 6f 63 28 29 5d 2c 20 74 68 65 6e 20 72 65  lloc()], then re
9c00: 74 75 72 6e 73 20 61 6c 6c 20 6f 66 20 74 68 65  turns all of the
9c10: 20 72 65 73 75 6c 74 20 61 66 74 65 72 20 74 68   result after th
9c20: 65 0a 2a 2a 20 71 75 65 72 79 20 68 61 73 20 66  e.** query has f
9c30: 69 6e 69 73 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20  inished. .**.** 
9c40: 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 73  As an example, s
9c50: 75 70 70 6f 73 65 20 74 68 65 20 71 75 65 72 79  uppose the query
9c60: 20 72 65 73 75 6c 74 20 77 68 65 72 65 20 74 68   result where th
9c70: 69 73 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20  is table:.**.** 
9c80: 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
9c90: 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
9ca0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
9cb0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
9cc0: 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
9cd0: 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
9ce0: 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
9cf0: 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
9d00: 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
9d10: 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a  | 21.** </pre>.*
9d20: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
9d30: 61 72 67 75 6d 65 6e 74 20 77 65 72 65 20 26 61  argument were &a
9d40: 7a 52 65 73 75 6c 74 20 74 68 65 6e 20 61 66 74  zResult then aft
9d50: 65 72 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  er the function 
9d60: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 7a 52 65 73  returns.** azRes
9d70: 75 6c 74 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ult will contain
9d80: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64   the following d
9d90: 61 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ata:.**.** <pre>
9da0: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
9db0: 75 6c 74 5b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  ult[0] = "Name";
9dc0: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
9dd0: 75 6c 74 5b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  ult[1] = "Age";.
9de0: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
9df0: 6c 74 5b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  lt[2] = "Alice";
9e00: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
9e10: 75 6c 74 5b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  ult[3] = "43";.*
9e20: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
9e30: 74 5b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  t[4] = "Bob";.**
9e40: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
9e50: 5b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  [5] = "28";.**  
9e60: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 36        azResult[6
9e70: 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
9e80: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b         azResult[
9e90: 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
9ea0: 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 69 63  pre>.**.** Notic
9eb0: 65 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  e that there is 
9ec0: 61 6e 20 65 78 74 72 61 20 72 6f 77 20 6f 66 20  an extra row of 
9ed0: 64 61 74 61 20 63 6f 6e 74 61 69 6e 69 6e 67 20  data containing 
9ee0: 74 68 65 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 68 65  the column.** he
9ef0: 61 64 65 72 73 2e 20 20 42 75 74 20 74 68 65 20  aders.  But the 
9f00: 2a 6e 72 6f 77 20 72 65 74 75 72 6e 20 76 61 6c  *nrow return val
9f10: 75 65 20 69 73 20 73 74 69 6c 6c 20 33 2e 20 20  ue is still 3.  
9f20: 2a 6e 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 73  *ncolumn is.** s
9f30: 65 74 20 74 6f 20 32 2e 20 20 49 6e 20 67 65 6e  et to 2.  In gen
9f40: 65 72 61 6c 2c 20 74 68 65 20 6e 75 6d 62 65 72  eral, the number
9f50: 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 73 65 72   of values inser
9f60: 74 65 64 20 69 6e 74 6f 20 61 7a 52 65 73 75 6c  ted into azResul
9f70: 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 28 28 2a  t.** will be ((*
9f80: 6e 72 6f 77 29 20 2b 20 31 29 2a 28 2a 6e 63 6f  nrow) + 1)*(*nco
9f90: 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  lumn)..**.** Aft
9fa0: 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  er the calling f
9fb0: 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  unction has fini
9fc0: 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72  shed using the r
9fd0: 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64  esult, it should
9fe0: 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 72 65   .** pass the re
9ff0: 73 75 6c 74 20 64 61 74 61 20 70 6f 69 6e 74 65  sult data pointe
a000: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
a010: 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
a020: 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73  er to .** releas
a030: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
a040: 74 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e  t was malloc-ed.
a050: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
a060: 20 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71   way the .** [sq
a070: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
a080: 68 61 70 70 65 6e 73 2c 20 74 68 65 20 63 61 6c  happens, the cal
a090: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ling function mu
a0a0: 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
a0b0: 6c 6c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ll .** [sqlite3_
a0c0: 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
a0d0: 2e 20 20 4f 6e 6c 79 20 5b 73 71 6c 69 74 65 33  .  Only [sqlite3
a0e0: 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
a0f0: 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
a100: 65 20 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  e .** the memory
a110: 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
a120: 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
a130: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
a140: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
a150: 74 68 65 20 73 61 6d 65 20 61 73 20 66 72 6f 6d  the same as from
a160: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
a170: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
a180: 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
a190: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
a1a0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
a1b0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
a1c0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
a1d0: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
a1e0: 62 65 20 65 78 65 63 75 74 65 64 20 2a 2f 0a 20  be executed */. 
a1f0: 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74 70   char ***resultp
a200: 2c 20 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c  ,       /* Resul
a210: 74 20 77 72 69 74 74 65 6e 20 74 6f 20 61 20 63  t written to a c
a220: 68 61 72 20 2a 5b 5d 20 20 74 68 61 74 20 74 68  har *[]  that th
a230: 69 73 20 70 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a  is points to */.
a240: 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20    int *nrow,    
a250: 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
a260: 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
a270: 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
a280: 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e  /.  int *ncolumn
a290: 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  ,          /* Nu
a2a0: 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
a2b0: 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
a2c0: 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
a2d0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
a2e0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
a2f0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
a300: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
a310: 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
a320: 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
a330: 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
a340: 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
a350: 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
a360: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
a370: 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
a380: 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
a390: 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
a3a0: 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
a3b0: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
a3c0: 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
a3d0: 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
a3e0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
a3f0: 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
a400: 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
a410: 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
a420: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
a430: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
a440: 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
a450: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
a460: 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
a470: 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
a480: 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
a490: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
a4a0: 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20    Both routines 
a4b0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
a4c0: 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
a4d0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
a4e0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
a4f0: 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
a500: 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
a510: 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
a520: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c  ng..**.** In sql
a530: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
a540: 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
a550: 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
a560: 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
a570: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
a580: 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
a590: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
a5a0: 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
a5b0: 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
a5c0: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
a5d0: 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
a5e0: 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
a5f0: 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 4e 6f  t parameter.  No
a600: 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
a610: 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
a620: 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
a630: 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
a640: 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
a650: 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
a660: 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
a670: 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
a680: 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
a690: 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
a6a0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
a6b0: 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
a6c0: 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
a6d0: 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
a6e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
a6f0: 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
a700: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
a710: 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
a720: 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
a730: 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
a740: 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
a750: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
a760: 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
a770: 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
a780: 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
a790: 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
a7a0: 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
a7b0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
a7c0: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
a7d0: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
a7e0: 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
a7f0: 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
a800: 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
a810: 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
a820: 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
a830: 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
a840: 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
a850: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
a860: 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
a870: 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
a880: 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
a890: 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
a8a0: 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
a8b0: 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
a8c0: 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
a8d0: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
a8e0: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
a8f0: 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
a900: 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
a910: 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
a920: 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
a930: 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
a940: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
a950: 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
a960: 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
a970: 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
a980: 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
a990: 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
a9a0: 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
a9b0: 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
a9c0: 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
a9d0: 74 66 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  tf formatting op
a9e0: 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
a9f0: 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
aa00: 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
aa10: 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
aa20: 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  options..**.** T
aa30: 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
aa40: 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
aa50: 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
aa60: 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
aa70: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
aa80: 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
aa90: 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
aaa0: 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
aab0: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
aac0: 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
aad0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
aae0: 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
aaf0: 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  al.  By doubling
ab00: 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
ab10: 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
ab20: 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
ab30: 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
ab40: 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
ab50: 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
ab60: 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
ab70: 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74  mple, so some st
ab80: 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 63 6f  ring variable co
ab90: 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
aba0: 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
abb0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
abc0: 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
abd0: 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
abe0: 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
abf0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
ac00: 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
ac10: 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
ac20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
ac30: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
ac40: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
ac50: 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
ac60: 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
ac70: 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
ac80: 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
ac90: 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
aca0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
acb0: 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
acc0: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
acd0: 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
ace0: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
acf0: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
ad00: 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
ad10: 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
ad20: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
ad30: 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
ad40: 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
ad50: 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
ad60: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
ad70: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
ad80: 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
ad90: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
ada0: 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
adb0: 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
adc0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
add0: 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
ade0: 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
adf0: 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
ae00: 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
ae10: 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
ae20: 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
ae30: 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
ae40: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
ae50: 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
ae60: 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
ae70: 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
ae80: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
ae90: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
aea0: 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
aeb0: 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
aec0: 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
aed0: 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
aee0: 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77  ou.** should alw
aef0: 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
af00: 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
af10: 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
af20: 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c  o a string .** l
af30: 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  iteral..**.** Th
af40: 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
af50: 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
af60: 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
af70: 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
af80: 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
af90: 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
afa0: 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20 74 68  tring.  Or if th
afb0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
afc0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c  he argument.** l
afd0: 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
afe0: 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
aff0: 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
b000: 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 20 73  NULL" (without s
b010: 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29  ingle.** quotes)
b020: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
b030: 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c   %Q option.  So,
b040: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
b050: 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
b060: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
b070: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
b080: 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
b090: 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
b0a0: 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
b0b0: 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
b0c0: 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
b0d0: 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
b0e0: 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
b0f0: 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
b100: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
b110: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
b120: 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
b130: 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
b140: 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
b150: 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
b160: 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
b170: 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
b180: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
b190: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20  .**.** The "%z" 
b1a0: 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
b1b0: 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20  n works exactly 
b1c0: 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74  like "%s" with t
b1d0: 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
b1e0: 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
b1f0: 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
b200: 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
b210: 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
b220: 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
b230: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
b240: 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
b250: 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..*/.char *sqlit
b260: 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
b270: 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
b280: 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
b290: 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
b2a0: 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
b2b0: 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
b2c0: 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
b2d0: 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a  t char*, ...);..
b2e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b2f0: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
b300: 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
b310: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
b320: 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
b330: 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
b340: 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
b350: 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
b360: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
b370: 64 73 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ds.  The default
b380: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
b390: 2a 2a 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79  ** of the memory
b3a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
b3b0: 79 73 74 65 6d 20 75 73 65 73 20 74 68 65 20 6d  ystem uses the m
b3c0: 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
b3d0: 28 29 0a 2a 2a 20 61 6e 64 20 66 72 65 65 28 29  ().** and free()
b3e0: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
b3f0: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
b400: 61 72 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69  ary.  However, i
b410: 66 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  f .** SQLite is 
b420: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
b430: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72  e following C pr
b440: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
b450: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
b460: 74 65 3e 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  te> SQLITE_OMIT_
b470: 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
b480: 4e 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  N </blockquote>.
b490: 2a 2a 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 69 6d  **.** then no im
b4a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
b4b0: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 74 68 65  provided for the
b4c0: 73 65 20 72 6f 75 74 69 6e 65 73 20 62 79 0a 2a  se routines by.*
b4d0: 2a 20 53 51 4c 69 74 65 2e 20 20 54 68 65 20 61  * SQLite.  The a
b4e0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
b4f0: 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51  links against SQ
b500: 4c 69 74 65 20 69 73 0a 2a 2a 20 65 78 70 65 63  Lite is.** expec
b510: 74 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20 69  ted to provide i
b520: 74 73 20 6f 77 6e 20 69 6d 70 6c 65 6d 65 6e 74  ts own implement
b530: 61 74 69 6f 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  ation..*/.void *
b540: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
b550: 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
b560: 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
b570: 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
b580: 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
b590: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
b5a0: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
b5b0: 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
b5c0: 2a 0a 2a 2a 20 49 6e 20 61 64 64 69 74 69 6f 6e  *.** In addition
b5d0: 20 74 6f 20 74 68 65 20 62 61 73 69 63 20 74 68   to the basic th
b5e0: 72 65 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ree allocation r
b5f0: 6f 75 74 69 6e 65 73 20 0a 2a 2a 20 5b 73 71 6c  outines .** [sql
b600: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
b610: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b620: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
b630: 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 74 68  ealloc()],.** th
b640: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
b650: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 69 6e  ion subsystem in
b660: 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20  cluded with the 
b670: 53 51 4c 69 74 65 0a 2a 2a 20 73 6f 75 72 63 65  SQLite.** source
b680: 73 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 69  s provides the i
b690: 6e 74 65 72 66 61 63 65 73 20 73 68 6f 77 6e 20  nterfaces shown 
b6a0: 62 65 6c 6f 77 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  below..**.** The
b6b0: 20 66 69 72 73 74 20 6f 66 20 74 68 65 73 65 20   first of these 
b6c0: 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  two routines ret
b6d0: 75 72 6e 73 20 74 68 65 20 61 6d 6f 75 6e 74 20  urns the amount 
b6e0: 6f 66 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 63 75  of memory .** cu
b6f0: 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
b700: 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
b710: 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 20 20 54  t not freed).  T
b720: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 74  he second.** ret
b730: 75 72 6e 73 20 74 68 65 20 6c 61 72 67 65 73 74  urns the largest
b740: 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 61   instantaneous a
b750: 6d 6f 75 6e 74 20 6f 66 20 6f 75 74 73 74 61 6e  mount of outstan
b760: 64 69 6e 67 0a 2a 2a 20 6d 65 6d 6f 72 79 2e 20  ding.** memory. 
b770: 20 54 68 65 20 68 69 67 68 77 61 74 65 72 20 6d   The highwater m
b780: 61 72 6b 20 69 73 20 72 65 73 65 74 20 69 66 20  ark is reset if 
b790: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  the argument is.
b7a0: 2a 2a 20 74 72 75 65 2e 20 20 54 68 65 20 53 51  ** true.  The SQ
b7b0: 4c 69 74 65 20 63 6f 72 65 20 64 6f 65 73 20 6e  Lite core does n
b7c0: 6f 74 20 75 73 65 20 65 69 74 68 65 72 20 6f 66  ot use either of
b7d0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
b7e0: 2a 2a 20 61 6e 64 20 73 6f 20 74 68 65 79 20 64  ** and so they d
b7f0: 6f 20 6e 6f 74 20 68 61 76 65 20 74 6f 20 62 65  o not have to be
b800: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
b810: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  the application.
b820: 2a 2a 20 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ** if SQLITE_OMI
b830: 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
b840: 49 4f 4e 20 69 73 20 64 65 66 69 6e 65 64 2e 20  ION is defined. 
b850: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   These routines.
b860: 2a 2a 20 61 72 65 20 70 72 6f 76 69 64 65 64 20  ** are provided 
b870: 62 79 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  by the default m
b880: 65 6d 6f 72 79 20 73 75 62 73 79 73 74 65 6d 20  emory subsystem 
b890: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 0a 2a  for diagnostic.*
b8a0: 2a 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2f 0a 73  * purposes..*/.s
b8b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
b8c0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
b8d0: 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
b8e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
b8f0: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
b900: 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
b910: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b920: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
b930: 6e 20 41 6c 61 72 6d 73 0a 2a 2a 0a 2a 2a 20 54  n Alarms.**.** T
b940: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
b950: 72 79 5f 61 6c 61 72 6d 5d 20 72 6f 75 74 69 6e  ry_alarm] routin
b960: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67  e is used to reg
b970: 69 73 74 65 72 0a 2a 2a 20 61 20 63 61 6c 6c 62  ister.** a callb
b980: 61 63 6b 20 6f 6e 20 6d 65 6d 6f 72 79 20 61 6c  ack on memory al
b990: 6c 6f 63 61 74 69 6f 6e 20 65 76 65 6e 74 73 2e  location events.
b9a0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
b9b0: 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 6f 72  ine registers or
b9c0: 20 63 6c 65 61 72 73 20 61 20 63 61 6c 6c 62 61   clears a callba
b9d0: 63 6b 73 20 74 68 61 74 20 66 69 72 65 73 20 77  cks that fires w
b9e0: 68 65 6e 0a 2a 2a 20 74 68 65 20 61 6d 6f 75 6e  hen.** the amoun
b9f0: 74 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t of memory allo
ba00: 63 61 74 65 64 20 65 78 63 65 65 64 73 20 69 54  cated exceeds iT
ba10: 68 72 65 73 68 6f 6c 64 2e 20 20 4f 6e 6c 79 0a  hreshold.  Only.
ba20: 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  ** a single call
ba30: 62 61 63 6b 20 63 61 6e 20 62 65 20 72 65 67 69  back can be regi
ba40: 73 74 65 72 65 64 20 61 74 20 61 20 74 69 6d 65  stered at a time
ba50: 2e 20 20 45 61 63 68 20 63 61 6c 6c 0a 2a 2a 20  .  Each call.** 
ba60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  to [sqlite3_memo
ba70: 72 79 5f 61 6c 61 72 6d 28 29 5d 20 6f 76 65 72  ry_alarm()] over
ba80: 77 72 69 74 65 73 20 74 68 65 20 70 72 65 76 69  writes the previ
ba90: 6f 75 73 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ous callback..**
baa0: 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
bab0: 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
bac0: 74 69 6e 67 20 78 43 61 6c 6c 62 61 63 6b 20 74  ting xCallback t
bad0: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
bae0: 74 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  ter..** .** The 
baf0: 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
bb00: 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 74  e callback are t
bb10: 68 65 20 70 41 72 67 20 76 61 6c 75 65 2c 20 74  he pArg value, t
bb20: 68 65 20 0a 2a 2a 20 61 6d 6f 75 6e 74 20 6f 66  he .** amount of
bb30: 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
bb40: 79 20 69 6e 20 75 73 65 2c 20 61 6e 64 20 74 68  y in use, and th
bb50: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  e size of the.**
bb60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74   allocation that
bb70: 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 63 61   provoked the ca
bb80: 6c 6c 62 61 63 6b 2e 20 20 54 68 65 20 63 61 6c  llback.  The cal
bb90: 6c 62 61 63 6b 20 77 69 6c 6c 0a 2a 2a 20 70 72  lback will.** pr
bba0: 65 73 75 6d 61 62 6c 79 20 69 6e 76 6f 6b 65 20  esumably invoke 
bbb0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
bbc0: 20 74 6f 20 66 72 65 65 20 75 70 20 6d 65 6d 6f   to free up memo
bbd0: 72 79 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65  ry space..** The
bbe0: 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 69 6e   callback may in
bbf0: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61  voke [sqlite3_ma
bc00: 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
bc10: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
bc20: 2a 20 62 75 74 20 69 66 20 69 74 20 64 6f 65 73  * but if it does
bc30: 2c 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  , no additional 
bc40: 63 61 6c 6c 62 61 63 6b 73 20 77 69 6c 6c 20 62  callbacks will b
bc50: 65 20 69 6e 76 6f 6b 65 64 20 62 79 0a 2a 2a 20  e invoked by.** 
bc60: 74 68 65 20 72 65 63 75 72 73 69 76 65 20 63 61  the recursive ca
bc70: 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  lls..**.** The [
bc80: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
bc90: 70 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  p_limit()] inter
bca0: 66 61 63 65 20 77 6f 72 6b 73 20 62 79 20 72 65  face works by re
bcb0: 67 69 73 74 65 72 69 6e 67 0a 2a 2a 20 61 20 6d  gistering.** a m
bcc0: 65 6d 6f 72 79 20 61 6c 61 72 6d 20 61 74 20 74  emory alarm at t
bcd0: 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
bce0: 69 74 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20  it and invoking 
bcf0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  .** [sqlite3_rel
bd00: 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69  ease_memory()] i
bd10: 6e 20 74 68 65 20 61 6c 61 72 6d 20 63 61 6c 6c  n the alarm call
bd20: 62 61 63 6b 2e 20 20 41 70 70 6c 69 63 61 74 69  back.  Applicati
bd30: 6f 6e 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 20 73  on.** programs s
bd40: 68 6f 75 6c 64 20 6e 6f 74 20 61 74 74 65 6d 70  hould not attemp
bd50: 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
bd60: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
bd70: 72 6d 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  rm()].** interfa
bd80: 63 65 20 62 65 63 61 75 73 65 20 64 6f 69 6e 67  ce because doing
bd90: 20 73 6f 20 77 69 6c 6c 20 69 6e 74 65 72 66 65   so will interfe
bda0: 72 65 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  re with the.** [
bdb0: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
bdc0: 70 5f 6c 69 6d 69 74 28 29 5d 20 6d 6f 64 75 6c  p_limit()] modul
bdd0: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
bde0: 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 0a  3_memory_alarm(.
bdf0: 20 20 76 6f 69 64 28 2a 78 43 61 6c 6c 62 61 63    void(*xCallbac
be00: 6b 29 28 76 6f 69 64 20 2a 70 41 72 67 2c 20 73  k)(void *pArg, s
be10: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 75 73 65  qlite3_int64 use
be20: 64 2c 20 69 6e 74 20 4e 29 2c 0a 20 20 76 6f 69  d, int N),.  voi
be30: 64 20 2a 70 41 72 67 2c 0a 20 20 73 71 6c 69 74  d *pArg,.  sqlit
be40: 65 33 5f 69 6e 74 36 34 20 69 54 68 72 65 73 68  e3_int64 iThresh
be50: 6f 6c 64 0a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  old.);.../*.** C
be60: 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
be70: 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
be80: 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
be90: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
bea0: 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75  e registers a au
beb0: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
bec0: 6b 20 77 69 74 68 20 74 68 65 20 53 51 4c 69 74  k with the SQLit
bed0: 65 20 6c 69 62 72 61 72 79 2e 20 20 0a 2a 2a 20  e library.  .** 
bee0: 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
bef0: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
bf00: 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
bf10: 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
bf20: 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
bf30: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
bf40: 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
bf50: 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
bf60: 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
bf70: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
bf80: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
bf90: 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
bfa0: 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20    At various.** 
bfb0: 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
bfc0: 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
bfd0: 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
bfe0: 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
bff0: 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
c000: 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
c010: 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
c020: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
c030: 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
c040: 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
c050: 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20  e allowed.  The 
c060: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
c070: 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
c080: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 74  turn SQLITE_OK t
c090: 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
c0a0: 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
c0b0: 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
c0c0: 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
c0d0: 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
c0e0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
c0f0: 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
c100: 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
c110: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
c120: 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
c130: 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
c140: 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
c150: 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
c160: 72 72 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 44 65  rror.  .**.** De
c170: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 61  pending on the a
c180: 63 74 69 6f 6e 2c 20 74 68 65 20 5b 53 51 4c 49  ction, the [SQLI
c190: 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b  TE_IGNORE] and [
c1a0: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 72 65 74  SQLITE_DENY] ret
c1b0: 75 72 6e 0a 2a 2a 20 63 6f 64 65 73 20 6d 69 67  urn.** codes mig
c1c0: 68 74 20 6d 65 61 6e 20 73 6f 6d 65 74 68 69 6e  ht mean somethin
c1d0: 67 20 64 69 66 66 65 72 65 6e 74 20 6f 72 20 74  g different or t
c1e0: 68 65 79 20 6d 69 67 68 74 20 6d 65 61 6e 20 74  hey might mean t
c1f0: 68 65 20 73 61 6d 65 0a 2a 2a 20 74 68 69 6e 67  he same.** thing
c200: 2e 20 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e  .  If the action
c210: 20 69 73 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   is, for example
c220: 2c 20 74 6f 20 70 65 72 66 6f 72 6d 20 61 20 64  , to perform a d
c230: 65 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e 2c 0a  elete opertion,.
c240: 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  ** then [SQLITE_
c250: 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c  IGNORE] and [SQL
c260: 49 54 45 5f 44 45 4e 59 5d 20 62 6f 74 68 20 63  ITE_DENY] both c
c270: 61 75 73 65 20 74 68 65 20 73 74 61 74 65 6d 65  ause the stateme
c280: 6e 74 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 0a 2a  nt compilation.*
c290: 2a 20 74 6f 20 66 61 69 6c 20 77 69 74 68 20 61  * to fail with a
c2a0: 6e 20 65 72 72 6f 72 2e 20 20 42 75 74 20 69 66  n error.  But if
c2b0: 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 74   the action is t
c2c0: 6f 20 72 65 61 64 20 61 20 73 70 65 63 69 66 69  o read a specifi
c2d0: 63 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 72 6f 6d  c column.** from
c2e0: 20 61 20 73 70 65 63 69 66 69 63 20 74 61 62 6c   a specific tabl
c2f0: 65 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  e, then [SQLITE_
c300: 44 45 4e 59 5d 20 77 69 6c 6c 20 63 61 75 73 65  DENY] will cause
c310: 20 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73   the entire.** s
c320: 74 61 74 65 6d 65 6e 74 20 74 6f 20 66 61 69 6c  tatement to fail
c330: 20 62 75 74 20 5b 53 51 4c 49 54 45 5f 49 47 4e   but [SQLITE_IGN
c340: 4f 52 45 5d 20 77 69 6c 6c 20 63 61 75 73 65 20  ORE] will cause 
c350: 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20  a NULL value to 
c360: 62 65 0a 2a 2a 20 72 65 61 64 20 69 6e 73 74 65  be.** read inste
c370: 61 64 20 6f 66 20 74 68 65 20 61 63 74 75 61 6c  ad of the actual
c380: 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a   column value..*
c390: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
c3a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
c3b0: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
c3c0: 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
c3d0: 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61  .** the third pa
c3e0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
c3f0: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
c400: 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
c410: 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  e..** The second
c420: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
c430: 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
c440: 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51   integer .** [SQ
c450: 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
c460: 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
c470: 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74  ecifies the part
c480: 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a  icular action.**
c490: 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
c4a0: 64 2e 20 20 54 68 65 20 61 76 61 69 6c 61 62 6c  d.  The availabl
c4b0: 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 61  e action codes a
c4c0: 72 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  re.** [SQLITE_CO
c4d0: 50 59 20 7c 20 64 6f 63 75 6d 65 6e 74 65 64 20  PY | documented 
c4e0: 73 65 70 61 72 61 74 65 6c 79 5d 2e 20 20 54 68  separately].  Th
c4f0: 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
c500: 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74  sixth.** paramet
c510: 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ers to the callb
c520: 61 63 6b 20 61 72 65 20 73 74 72 69 6e 67 73 20  ack are strings 
c530: 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
c540: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
c550: 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
c560: 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
c570: 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ized..**.** An a
c580: 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
c590: 64 20 77 68 65 6e 20 70 72 65 70 61 72 69 6e 67  d when preparing
c5a0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
c5b0: 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
c5c0: 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74 6f 20  d.** source, to 
c5d0: 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
c5e0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 64  SQL statements d
c5f0: 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
c600: 65 73 73 20 64 61 74 61 0a 2a 2a 20 74 68 61 74  ess data.** that
c610: 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
c620: 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
c630: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
c640: 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78 65 63  t try to.** exec
c650: 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
c660: 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
c670: 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
c680: 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
c690: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
c6a0: 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
c6b0: 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
c6c0: 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
c6d0: 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
c6e0: 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
c6f0: 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
c700: 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
c710: 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
c720: 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
c730: 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
c740: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
c750: 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
c760: 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
c770: 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
c780: 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
c790: 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
c7a0: 53 51 4c 20 69 73 20 62 65 69 6e 67 20 70 72 65  SQL is being pre
c7b0: 70 61 72 65 64 20 74 68 61 74 20 64 69 73 61 6c  pared that disal
c7c0: 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 0a  lows everything.
c7d0: 2a 2a 20 65 78 63 65 70 74 20 53 45 4c 45 43 54  ** except SELECT
c7e0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 0a 2a   statements.  .*
c7f0: 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67  *.** Only a sing
c800: 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
c810: 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
c820: 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
c830: 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
c840: 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
c850: 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
c860: 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
c870: 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
c880: 6f 75 73 20 63 61 6c 6c 2e 20 20 41 20 4e 55 4c  ous call.  A NUL
c890: 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61  L authorizer mea
c8a0: 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f  ns that no autho
c8b0: 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
c8c0: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
c8d0: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75    The default au
c8e0: 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c  thorizer is NULL
c8f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
c900: 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
c910: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
c920: 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
c930: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72   .** [sqlite3_pr
c940: 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
c950: 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
c960: 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
c970: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
c980: 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
c990: 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
c9a0: 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2f  ite3_step()]..*/
c9b0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
c9c0: 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
c9d0: 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
c9e0: 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
c9f0: 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
ca00: 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
ca10: 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
ca20: 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
ca30: 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
ca40: 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
ca50: 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
ca60: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
ca70: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
ca80: 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
ca90: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
caa0: 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
cab0: 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
cac0: 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
cad0: 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
cae0: 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
caf0: 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
cb00: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
cb10: 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
cb20: 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
cb30: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
cb40: 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
cb50: 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
cb60: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
cb70: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
cb80: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69  mation..*/.#defi
cb90: 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
cba0: 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
cbb0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
cbc0: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
cbd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cbe0: 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
cbf0: 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
cc00: 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
cc10: 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
cc20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
cc30: 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
cc40: 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
cc50: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
cc60: 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
cc70: 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
cc80: 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
cc90: 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
cca0: 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
ccb0: 68 6f 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20  horizer certain 
ccc0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
ccd0: 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
cce0: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
ccf0: 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
cd00: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
cd10: 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
cd20: 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
cd30: 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
cd40: 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
cd50: 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
cd60: 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
cd70: 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
cd80: 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
cd90: 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
cda0: 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
cdb0: 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
cdc0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
cdd0: 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  ration is to be 
cde0: 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
cdf0: 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
ce00: 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
ce10: 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
ce20: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
ce30: 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
ce40: 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
ce50: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
ce60: 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
ce70: 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
ce80: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
ce90: 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20  meter.  The 5th 
cea0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
ceb0: 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
cec0: 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
ced0: 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
cee0: 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
cef0: 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69  mp", .** etc.) i
cf00: 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54  f applicable.  T
cf10: 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
cf20: 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
cf30: 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
cf40: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
cf50: 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
cf60: 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
cf70: 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
cf80: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
cf90: 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
cfa0: 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
cfb0: 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
cfc0: 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74  ectly from .** t
cfd0: 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
cfe0: 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
cff0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d000: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d010: 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
d020: 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
d030: 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
d040: 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
d050: 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
d060: 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
d070: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
d080: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d090: 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
d0a0: 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
d0b0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
d0c0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
d0d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d0e0: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
d0f0: 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
d100: 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
d110: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
d120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d130: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
d140: 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
d150: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
d160: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
d170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d180: 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
d190: 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
d1a0: 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
d1b0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
d1c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d1d0: 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
d1e0: 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
d1f0: 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
d200: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
d210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
d220: 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
d230: 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
d240: 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
d250: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
d260: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
d270: 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
d280: 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
d290: 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
d2a0: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
d2b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
d2c0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
d2d0: 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
d2e0: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
d2f0: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
d300: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
d310: 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
d320: 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
d330: 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
d340: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
d350: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
d360: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
d370: 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
d380: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
d390: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
d3a0: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
d3b0: 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
d3c0: 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
d3d0: 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
d3e0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
d3f0: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
d400: 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
d410: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
d420: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
d430: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
d440: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
d450: 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
d460: 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
d470: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
d480: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
d490: 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
d4a0: 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
d4b0: 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
d4c0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
d4d0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
d4e0: 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
d4f0: 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
d500: 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
d510: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
d520: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
d530: 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
d540: 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
d550: 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
d560: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
d570: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d580: 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
d590: 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
d5a0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
d5b0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
d5c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d5d0: 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
d5e0: 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
d5f0: 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
d600: 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
d610: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d620: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
d630: 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
d640: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
d650: 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
d660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d670: 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
d680: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
d690: 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
d6a0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
d6b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
d6c0: 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
d6d0: 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c      22   /* NULL
d6e0: 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
d6f0: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
d700: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
d710: 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
d720: 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
d730: 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
d740: 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
d750: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
d760: 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
d770: 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
d780: 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
d790: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
d7a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
d7b0: 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
d7c0: 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
d7d0: 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
d7e0: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
d7f0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
d800: 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
d810: 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
d820: 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
d830: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
d840: 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
d850: 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
d860: 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
d870: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
d880: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
d890: 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
d8b0: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
d8c0: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
d8d0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
d8e0: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
d8f0: 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
d900: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
d910: 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
d920: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
d930: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
d940: 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
d950: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
d960: 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
d970: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
d980: 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
d990: 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
d9a0: 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65  /* Function Name
d9b0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
d9c0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
d9d0: 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
d9e0: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
d9f0: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
da00: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
da10: 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
da20: 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
da30: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
da40: 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
da50: 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
da60: 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
da70: 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
da80: 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
da90: 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
daa0: 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
dab0: 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  nts..** The call
dac0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
dad0: 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
dae0: 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
daf0: 6e 76 6f 6b 65 64 0a 2a 2a 20 61 74 20 74 68 65  nvoked.** at the
db00: 20 66 69 72 73 74 20 5b 73 71 6c 69 74 65 33 5f   first [sqlite3_
db10: 73 74 65 70 28 29 5d 20 66 6f 72 20 74 68 65 20  step()] for the 
db20: 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
db30: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
db40: 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
db50: 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
db60: 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
db70: 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
db80: 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
db90: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
dba0: 69 73 68 65 73 20 61 6e 64 20 69 6e 63 6c 75 64  ishes and includ
dbb0: 65 73 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  es.** informatio
dbc0: 6e 20 6f 6e 20 68 6f 77 20 6c 6f 6e 67 20 74 68  n on how long th
dbd0: 61 74 20 73 74 61 74 65 6d 65 6e 74 20 72 61 6e  at statement ran
dbe0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
dbf0: 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50  te3_profile() AP
dc00: 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  I is currently c
dc10: 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
dc20: 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73  mental and.** is
dc30: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
dc40: 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ge..*/.void *sql
dc50: 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
dc60: 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
dc70: 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
dc80: 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  har*), void*);.v
dc90: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
dca0: 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
dcb0: 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
dcc0: 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
dcd0: 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
dce0: 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
dcf0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
dd00: 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
dd10: 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 69  lbacks.**.** Thi
dd20: 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67  s routine config
dd30: 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ures a callback 
dd40: 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 20 70  function - the p
dd50: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
dd60: 20 2d 20 74 68 61 74 0a 2a 2a 20 69 73 20 69 6e   - that.** is in
dd70: 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
dd80: 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
dd90: 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20  unning calls to 
dda0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
ddb0: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  ,.** [sqlite3_st
ddc0: 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
ddd0: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e  e3_get_table()].
dde0: 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
ddf0: 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e   for this .** in
de00: 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
de10: 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
de20: 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
de30: 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  query..**.** The
de40: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
de50: 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
de60: 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76  ce for every N v
de70: 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 6f  irtual machine o
de80: 70 63 6f 64 65 73 2c 0a 2a 2a 20 77 68 65 72 65  pcodes,.** where
de90: 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
dea0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
deb0: 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  s function. The 
dec0: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
ded0: 6b 0a 2a 2a 20 69 74 73 65 6c 66 20 69 73 20 69  k.** itself is i
dee0: 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
def0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
df00: 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
df10: 2e 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20  . The fourth.** 
df20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
df30: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 76   function is a v
df40: 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73  oid pointer pass
df50: 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65  ed to the progre
df60: 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  ss callback.** f
df70: 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d  unction each tim
df80: 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e  e it is invoked.
df90: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c  .**.** If a call
dfa0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
dfb0: 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
dfc0: 74 65 70 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  tep()], or [sqli
dfd0: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
dfe0: 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 20 66  .** results in f
dff0: 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f  ewer than N opco
e000: 64 65 73 20 62 65 69 6e 67 20 65 78 65 63 75 74  des being execut
e010: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f  ed, then the pro
e020: 67 72 65 73 73 20 0a 2a 2a 20 63 61 6c 6c 62 61  gress .** callba
e030: 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f  ck is never invo
e040: 6b 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e 6c 79  ked..** .** Only
e050: 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
e060: 73 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ss callback func
e070: 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
e080: 73 74 65 72 65 64 20 66 6f 72 20 65 61 63 68 0a  stered for each.
e090: 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  ** open database
e0a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 45 76   connection.  Ev
e0b0: 65 72 79 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ery call to sqli
e0c0: 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
e0d0: 64 6c 65 72 28 29 0a 2a 2a 20 6f 76 65 72 77 72  dler().** overwr
e0e0: 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 73  ites the results
e0f0: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
e100: 20 63 61 6c 6c 2e 0a 2a 2a 20 54 6f 20 72 65 6d   call..** To rem
e110: 6f 76 65 20 74 68 65 20 70 72 6f 67 72 65 73 73  ove the progress
e120: 20 63 61 6c 6c 62 61 63 6b 20 61 6c 74 6f 67 65   callback altoge
e130: 74 68 65 72 2c 20 70 61 73 73 20 4e 55 4c 4c 20  ther, pass NULL 
e140: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
e150: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
e160: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
e170: 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
e180: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
e190: 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72  s a result other
e1a0: 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 20 74 68   than 0, then th
e1b0: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 71 75  e current .** qu
e1c0: 65 72 79 20 69 73 20 69 6d 6d 65 64 69 61 74 65  ery is immediate
e1d0: 6c 79 20 74 65 72 6d 69 6e 61 74 65 64 20 61 6e  ly terminated an
e1e0: 64 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  d any database c
e1f0: 68 61 6e 67 65 73 20 72 6f 6c 6c 65 64 20 62 61  hanges rolled ba
e200: 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 61  ck..** The conta
e210: 69 6e 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  ining [sqlite3_e
e220: 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
e230: 5f 73 74 65 70 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _step()], or.** 
e240: 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
e250: 6c 65 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72  le()] call retur
e260: 6e 73 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ns SQLITE_INTERR
e270: 55 50 54 2e 20 20 20 54 68 69 73 20 66 65 61 74  UPT.   This feat
e280: 75 72 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ure.** can be us
e290: 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
e2a0: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
e2b0: 65 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  e "Cancel" butto
e2c0: 6e 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f 67 72 65  n on a.** progre
e2d0: 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 20 69 6e  ss dialog box in
e2e0: 20 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f 69 64 20   a GUI..*/.void 
e2f0: 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
e300: 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
e310: 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
e320: 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
e330: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e340: 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
e350: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
e360: 6e 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 74 68 65  n.**.** Open the
e370: 20 73 71 6c 69 74 65 20 64 61 74 61 62 61 73 65   sqlite database
e380: 20 66 69 6c 65 20 22 66 69 6c 65 6e 61 6d 65 22   file "filename"
e390: 2e 20 20 54 68 65 20 22 66 69 6c 65 6e 61 6d 65  .  The "filename
e3a0: 22 20 69 73 20 55 54 46 2d 38 0a 2a 2a 20 65 6e  " is UTF-8.** en
e3b0: 63 6f 64 65 64 20 66 6f 72 20 73 71 6c 69 74 65  coded for sqlite
e3c0: 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 55 54 46  3_open() and UTF
e3d0: 2d 31 36 20 65 6e 63 6f 64 65 64 20 69 6e 20 74  -16 encoded in t
e3e0: 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
e3f0: 72 64 65 72 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  rder.** for sqli
e400: 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 20 41  te3_open16().  A
e410: 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  n [sqlite3*] han
e420: 64 6c 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  dle is returned 
e430: 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a  in *ppDb, even.*
e440: 2a 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  * if an error oc
e450: 63 75 72 73 2e 20 49 66 20 74 68 65 20 64 61 74  curs. If the dat
e460: 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
e470: 28 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  (or created) suc
e480: 63 65 73 73 66 75 6c 6c 79 2c 0a 2a 2a 20 74 68  cessfully,.** th
e490: 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  en [SQLITE_OK] i
e4a0: 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65  s returned. Othe
e4b0: 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 63  rwise an error c
e4c0: 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ode is returned.
e4d0: 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
e4e0: 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
e4f0: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
e500: 29 5d 20 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  )]  routines can
e510: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
e520: 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
e530: 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
e540: 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
e550: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  or..**.** If the
e560: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
e570: 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2c 20 74  oes not exist, t
e580: 68 65 6e 20 61 20 6e 65 77 20 64 61 74 61 62 61  hen a new databa
e590: 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
e5a0: 65 64 0a 2a 2a 20 61 73 20 6e 65 65 64 65 64 2e  ed.** as needed.
e5b0: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e    The default en
e5c0: 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
e5d0: 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
e5e0: 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
e5f0: 74 65 33 5f 6f 70 65 6e 28 29 20 69 73 20 63 61  te3_open() is ca
e600: 6c 6c 65 64 20 61 6e 64 20 55 54 46 2d 31 36 20  lled and UTF-16 
e610: 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
e620: 36 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  6 is used..**.**
e630: 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
e640: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
e650: 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
e660: 64 2c 20 72 65 73 6f 75 72 63 65 73 20 61 73 73  d, resources ass
e670: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
e680: 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68  the [sqlite3*] h
e690: 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
e6a0: 72 65 6c 65 61 73 65 64 20 62 79 20 70 61 73 73  released by pass
e6b0: 69 6e 67 20 69 74 20 74 6f 0a 2a 2a 20 5b 73 71  ing it to.** [sq
e6c0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
e6d0: 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
e6e0: 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
e6f0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e700: 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
e710: 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
e720: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 65 78  qlite3_open() ex
e730: 63 65 70 74 20 74 68 61 74 0a 2a 2a 20 70 72 6f  cept that.** pro
e740: 76 69 64 65 73 20 74 77 6f 20 61 64 64 69 74 69  vides two additi
e750: 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
e760: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
e770: 6f 6e 74 72 6f 6c 20 6f 76 65 72 20 74 68 65 0a  ontrol over the.
e780: 2a 2a 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  ** new database 
e790: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
e7a0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
e7b0: 20 63 61 6e 20 62 65 20 6f 6e 65 20 6f 66 3a 0a   can be one of:.
e7c0: 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
e7d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e7e0: 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c  _READONLY].** <l
e7f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e800: 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a 2a 20 3c  _READWRITE].** <
e810: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e820: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
e830: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
e840: 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  TE].** </ol>.**.
e850: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 76 61 6c  ** The first val
e860: 75 65 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74  ue opens the dat
e870: 61 62 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  abase read-only.
e880: 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
e890: 65 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 70 72  e does.** not pr
e8a0: 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20  eviously exist, 
e8b0: 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
e8c0: 72 6e 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  rned.  The secon
e8d0: 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  d option opens.*
e8e0: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  * the database f
e8f0: 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
e900: 72 69 74 69 6e 67 20 62 75 74 20 74 68 65 20 64  riting but the d
e910: 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
e920: 65 61 64 79 0a 2a 2a 20 65 78 69 73 74 20 6f 72  eady.** exist or
e930: 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
e940: 75 72 6e 65 64 2e 20 20 54 68 65 20 74 68 69 72  urned.  The thir
e950: 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 20 74  d option opens t
e960: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
e970: 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
e980: 72 69 74 69 6e 67 20 61 6e 64 20 63 72 65 61 74  riting and creat
e990: 65 73 20 69 74 20 69 66 20 69 74 20 64 6f 65 73  es it if it does
e9a0: 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
e9b0: 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  st..** The third
e9c0: 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 65 68 61   options is beha
e9d0: 76 69 6f 72 20 74 68 61 74 20 69 73 20 75 73 65  vior that is use
e9e0: 64 20 61 6c 77 61 79 73 20 66 6f 72 20 73 71 6c  d always for sql
e9f0: 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 61  ite3_open().** a
ea00: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
ea10: 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  6()..**.** The f
ea20: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
ea30: 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
ea40: 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
ea50: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
ea60: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
ea70: 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
ea80: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
ea90: 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  m .** interface 
eaa0: 74 68 61 74 20 74 68 65 20 6e 65 77 20 64 61 74  that the new dat
eab0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
eac0: 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66   should use.  If
ead0: 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
eae0: 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e 55  arameter is a NU
eaf0: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
eb00: 61 20 64 65 66 61 75 6c 74 20 73 75 69 74 61 62  a default suitab
eb10: 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 68 6f  le for.** the ho
eb20: 73 74 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 69  st environment i
eb30: 73 20 73 75 62 73 74 69 74 75 74 65 64 2e 0a 2a  s substituted..*
eb40: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 6f 20 77 69 6e  *.** Note to win
eb50: 64 6f 77 73 20 75 73 65 72 73 3a 20 20 54 68 65  dows users:  The
eb60: 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
eb70: 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
eb80: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
eb90: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6d 75  qlite3_open() mu
eba0: 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
ebb0: 20 77 68 61 74 65 76 65 72 20 63 6f 64 65 70 61   whatever codepa
ebc0: 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a  ge is currently.
ebd0: 2a 2a 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ** defined.  Fil
ebe0: 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
ebf0: 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 20  g international 
ec00: 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
ec10: 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
ec20: 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
ec30: 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
ec40: 6e 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nto sqlite3_open
ec50: 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()..*/.int sqlit
ec60: 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
ec70: 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
ec80: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
ec90: 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
eca0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
ecb0: 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
ecc0: 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
ecd0: 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
ece0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
ecf0: 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
ed00: 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
ed10: 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
ed20: 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
ed30: 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
ed40: 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
ed50: 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
ed60: 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
ed70: 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
ed80: 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
ed90: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
eda0: 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
edb0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
edc0: 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
edd0: 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
ede0: 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
edf0: 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
ee00: 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
ee10: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
ee20: 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
ee30: 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
ee40: 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
ee50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
ee60: 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
ee70: 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sages.**.** The 
ee80: 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
ee90: 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
eea0: 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a  rns the numeric.
eeb0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
eec0: 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
eed0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
eee0: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
eef0: 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f  sult code].** fo
ef00: 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
ef10: 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
ef20: 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
ef30: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b  ciated.** with [
ef40: 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20  sqlite3] handle 
ef50: 27 64 62 27 2e 20 20 49 66 20 61 20 70 72 69 6f  'db'.  If a prio
ef60: 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
ef70: 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73  d but the.** mos
ef80: 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
ef90: 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
efa0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
efb0: 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
efc0: 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66  de().** is undef
efd0: 69 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ined. .**.** The
efe0: 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
eff0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
f000: 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
f010: 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 61 75 67 65  English-langauge
f020: 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
f030: 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
f040: 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
f050: 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70 65  8 or UTF16 respe
f060: 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
f070: 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
f080: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
f090: 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
f0a0: 6e 74 65 72 6e 61 6c 6c 79 2e 20 20 54 68 65 20  nternally.  The 
f0b0: 0a 2a 2a 20 73 74 72 69 6e 67 20 6d 61 79 20 62  .** string may b
f0c0: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
f0d0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 20   deallocated by 
f0e0: 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
f0f0: 20 74 6f 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e   to SQLite.** in
f100: 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
f110: 73 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 73 20 74  s..**.** Calls t
f120: 6f 20 6d 61 6e 79 20 73 71 6c 69 74 65 33 5f 2a  o many sqlite3_*
f130: 20 66 75 6e 63 74 69 6f 6e 73 20 73 65 74 20 74   functions set t
f140: 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  he error code an
f150: 64 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  d string returne
f160: 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
f170: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71  _errcode()], [sq
f180: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
f190: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
f1a0: 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 28 6f 76  rmsg16()].** (ov
f1b0: 65 72 77 72 69 74 69 6e 67 20 74 68 65 20 70 72  erwriting the pr
f1c0: 65 76 69 6f 75 73 20 76 61 6c 75 65 73 29 2e 20  evious values). 
f1d0: 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 73 20  Note that calls 
f1e0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
f1f0: 6f 64 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ode()],.** [sqli
f200: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61  te3_errmsg()], a
f210: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
f220: 73 67 31 36 28 29 5d 20 74 68 65 6d 73 65 6c 76  sg16()] themselv
f230: 65 73 20 64 6f 20 6e 6f 74 20 61 66 66 65 63 74  es do not affect
f240: 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 73 20   the.** results 
f250: 6f 66 20 66 75 74 75 72 65 20 69 6e 76 6f 63 61  of future invoca
f260: 74 69 6f 6e 73 2e 20 20 43 61 6c 6c 73 20 74 6f  tions.  Calls to
f270: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68   API routines th
f280: 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e  at do not return
f290: 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64  .** an error cod
f2a0: 65 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c  e (example: [sql
f2b0: 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
f2c0: 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 63 68  )]) do not.** ch
f2d0: 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20 63  ange the error c
f2e0: 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  ode returned by 
f2f0: 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 49  this routine.  I
f300: 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61  nterfaces that a
f310: 72 65 0a 2a 2a 20 6e 6f 74 20 61 73 73 6f 63 69  re.** not associ
f320: 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63  ated with a spec
f330: 69 66 69 63 20 64 61 74 61 62 61 73 65 20 63 6f  ific database co
f340: 6e 6e 65 63 74 69 6f 6e 20 28 65 78 61 6d 70 6c  nnection (exampl
f350: 65 73 3a 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es:.** [sqlite3_
f360: 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73  mprintf()] or [s
f370: 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
f380: 61 72 65 64 5f 63 61 63 68 65 28 29 5d 20 64 6f  ared_cache()] do
f390: 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 74   not change.** t
f3a0: 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 20  he return code. 
f3b0: 20 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e 67   .**.** Assuming
f3c0: 20 6e 6f 20 6f 74 68 65 72 20 69 6e 74 65 72 76   no other interv
f3d0: 65 6e 69 6e 67 20 73 71 6c 69 74 65 33 5f 2a 20  ening sqlite3_* 
f3e0: 41 50 49 20 63 61 6c 6c 73 20 61 72 65 20 6d 61  API calls are ma
f3f0: 64 65 2c 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  de, the error.**
f400: 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62   code returned b
f410: 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
f420: 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
f430: 74 68 20 74 68 65 20 73 61 6d 65 20 65 72 72 6f  th the same erro
f440: 72 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  r as.** the stri
f450: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
f460: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
f470: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
f480: 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a  errmsg16()]..*/.
f490: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
f4a0: 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
f4b0: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
f4c0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
f4d0: 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
f4e0: 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
f4f0: 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
f500: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f510: 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
f520: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 49 6e 73 74  bject.**.** Inst
f530: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
f540: 65 63 74 20 72 65 70 72 65 73 65 6e 74 20 73 69  ect represent si
f550: 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
f560: 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a 20 69 73  nts.  This.** is
f570: 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
f580: 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
f590: 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 20  statement" or a 
f5a0: 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
f5b0: 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
f5c0: 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
f5d0: 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20  tement"..** .** 
f5e0: 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
f5f0: 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
f600: 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
f610: 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
f620: 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
f630: 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
f640: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
f650: 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
f660: 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
f670: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
f680: 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
f690: 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
f6a0: 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b   using.**      [
f6b0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
f6c0: 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
f6d0: 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d 2e 0a  _* interfaces]..
f6e0: 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
f6f0: 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
f700: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
f710: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
f720: 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
f730: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
f740: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
f750: 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
f760: 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
f770: 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
f780: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
f790: 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
f7a0: 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
f7b0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
f7c0: 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
f7d0: 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
f7e0: 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
f7f0: 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
f800: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
f810: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
f820: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
f830: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
f840: 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
f850: 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
f860: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
f870: 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
f880: 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ment.**.** To ex
f890: 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
f8a0: 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
f8b0: 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
f8c0: 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
f8d0: 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
f8e0: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
f8f0: 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  tines. .**.** Th
f900: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f910: 20 22 64 62 22 20 69 73 20 61 6e 20 5b 73 71 6c   "db" is an [sql
f920: 69 74 65 33 20 7c 20 53 51 4c 69 74 65 20 64 61  ite3 | SQLite da
f930: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d 20 0a  tabase handle] .
f940: 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
f950: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
f960: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f970: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
f980: 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  en16()]..** The 
f990: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
f9a0: 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20 73 74  "zSql" is the st
f9b0: 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
f9c0: 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
f9d0: 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
f9e0: 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
f9f0: 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
fa00: 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
fa10: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
fa20: 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 73   interfaces uses
fa30: 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c 69 74   UTF-8 and sqlit
fa40: 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
fa50: 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
fa60: 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
fa70: 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49   UTF-16..**.** I
fa80: 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
fa90: 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a 2a 2a 20  ment is less.** 
faa0: 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
fab0: 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
fac0: 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
fad0: 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 49  o terminator.  I
fae0: 66 0a 2a 2a 20 6e 42 79 74 65 20 69 73 20 6e 6f  f.** nByte is no
faf0: 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
fb00: 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
fb10: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  um number of .**
fb20: 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
fb30: 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79   zSql.  When nBy
fb40: 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
fb50: 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
fb60: 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
fb70: 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
fb80: 27 5c 30 30 30 27 20 63 68 61 72 61 63 74 65 72  '\000' character
fb90: 20 6f 72 20 0a 2a 2a 20 75 6e 74 69 6c 20 74 68   or .** until th
fba0: 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
fbb0: 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
fbc0: 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 2a 70   first..**.** *p
fbd0: 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
fbe0: 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
fbf0: 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68  rst byte past th
fc00: 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
fc10: 73 74 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  st.** SQL statem
fc20: 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
fc30: 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
fc40: 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66 69 72  compiles the fir
fc50: 73 74 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  st statement.** 
fc60: 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
fc70: 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
fc80: 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d  ting to what rem
fc90: 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
fca0: 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69  .**.** *ppStmt i
fcb0: 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
fcc0: 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 0a 2a  to a compiled .*
fcd0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
fce0: 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  | SQL statement 
fcf0: 73 74 72 75 63 74 75 72 65 5d 20 74 68 61 74 20  structure] that 
fd00: 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
fd10: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
fd20: 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72 20 69  3_step()].  Or i
fd30: 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
fd40: 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 6d 61 79  ror, *ppStmt may
fd50: 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55   be.** set to NU
fd60: 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75  LL.  If the inpu
fd70: 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 65 64  t text contained
fd80: 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
fd90: 69 6e 70 75 74 20 69 73 20 61 6e 64 0a 2a 2a 20  input is and.** 
fda0: 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
fdb0: 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
fdc0: 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
fdd0: 6f 20 4e 55 4c 4c 2e 20 20 54 68 65 20 63 61 6c  o NULL.  The cal
fde0: 6c 69 6e 67 0a 2a 2a 20 70 72 6f 63 65 64 75 72  ling.** procedur
fdf0: 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
fe00: 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
fe10: 65 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  e compiled SQL s
fe20: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e  tatement.** usin
fe30: 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
fe40: 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
fe50: 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
fe60: 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  h it..**.** On s
fe70: 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
fe80: 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
fe90: 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 0a    Otherwise an .
fea0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
feb0: 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69   | error code] i
fec0: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
fed0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
fee0: 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
fef0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
ff00: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
ff10: 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
ff20: 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
ff30: 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
ff40: 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
ff50: 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
ff60: 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
ff70: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
ff80: 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
ff90: 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
ffa0: 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
ffb0: 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
ffc0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
ffd0: 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
ffe0: 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
fff0: 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
10000 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
10010 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69  of the .** origi
10020 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
10030 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
10040 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
10050 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
10060 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e  ehave a differen
10070 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a  tly in two ways:
10080 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
10090 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  li>.** If the da
100a0 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
100b0 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
100c0 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
100d0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
100e0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
100f0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
10100 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
10110 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
10120 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
10130 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
10140 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
10150 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65  in.  If the sche
10160 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
10170 6e 20 61 20 77 61 79 0a 2a 2a 20 74 68 61 74 20  n a way.** that 
10180 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
10190 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
101a0 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
101b0 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
101c0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
101d0 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
101e0 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
101f0 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
10200 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
10210 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
10220 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
10230 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
10240 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
10250 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
10260 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
10270 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
10280 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
10290 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 20 6f   find the text o
102a0 66 20 74 68 65 20 70 61 72 73 69 6e 67 0a 2a 2a  f the parsing.**
102b0 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
102c0 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
102d0 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
102e0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
102f0 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
10300 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a   error occurs, .
10310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
10320 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
10330 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
10340 6c 65 64 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  led .** [SQLITE_
10350 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63  ERROR | result c
10360 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  odes] or.** [SQL
10370 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
10380 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
10390 20 63 6f 64 65 73 5d 20 73 75 63 68 20 61 73 20   codes] such as 
103a0 64 69 72 65 63 74 6c 79 2e 0a 2a 2a 20 54 68 65  directly..** The
103b0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
103c0 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69 74   was that [sqlit
103d0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
103e0 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
103f0 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54  eneric.** [SQLIT
10400 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
10410 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f 75  code and you wou
10420 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
10430 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
10440 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
10450 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  et()] in order t
10460 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
10470 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
10480 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57  he problem..** W
10490 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
104a0 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 73 2c  pare interfaces,
104b0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
104c0 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
104d0 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75 72  rror is.** retur
104e0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
104f0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
10500 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
10510 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
10520 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
10530 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
10540 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
10550 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
10560 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
10570 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
10580 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
10590 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
105a0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
105b0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
105c0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
105d0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
105e0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
105f0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
10600 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
10610 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
10620 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
10630 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
10640 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
10650 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
10660 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
10670 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
10680 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
10690 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
106a0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
106b0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
106c0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
106d0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
106e0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
106f0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
10700 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
10710 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
10720 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
10730 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
10740 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
10750 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
10760 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
10770 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
10780 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
10790 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
107a0 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
107b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
107c0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
107d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
107e0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
107f0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
10800 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
10810 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
10820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
10830 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
10840 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
10850 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
10860 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
10870 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
10880 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
10890 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
108a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
108b0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
108c0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
108d0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
108e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
108f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
10900 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
10910 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
10920 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
10930 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
10940 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
10950 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
10960 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
10970 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
10980 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
10990 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
109a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
109b0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
109c0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
109d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
109e0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
109f0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
10a00 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
10a10 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
10a20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
10a30 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
10a40 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
10a50 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
10a60 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 20   dynamic typing 
10a70 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
10a80 74 20 73 74 6f 72 65 73 2e 20 20 56 61 6c 75 65  t stores.  Value
10a90 73 20 63 61 6e 20 0a 2a 2a 20 62 65 20 69 6e 74  s can .** be int
10aa0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
10ab0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
10ac0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
10ad0 20 4e 55 4c 4c 2e 20 20 57 68 65 6e 0a 2a 2a 20   NULL.  When.** 
10ae0 70 61 73 73 69 6e 67 20 61 72 6f 75 6e 64 20 76  passing around v
10af0 61 6c 75 65 73 20 69 6e 74 65 72 6e 61 6c 6c 79  alues internally
10b00 2c 20 65 61 63 68 20 76 61 6c 75 65 20 69 73 20  , each value is 
10b10 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 0a 2a  represented as.*
10b20 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * an instance of
10b30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
10b40 75 65 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  ue object..*/.ty
10b50 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
10b60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
10b70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10b80 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43    SQL Function C
10b90 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
10ba0 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
10bb0 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
10bc0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
10bd0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
10be0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
10bf0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20  text object.  A 
10c00 70 6f 69 6e 74 65 72 20 74 6f 20 73 75 63 68 20  pointer to such 
10c10 61 6e 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  an object is the
10c20 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65  .** first parame
10c30 74 65 72 20 74 6f 20 75 73 65 72 2d 64 65 66 69  ter to user-defi
10c40 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
10c50 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
10c60 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
10c70 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
10c80 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
10c90 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e 67 20  I3REF:  Binding 
10ca0 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
10cb0 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
10cc0 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73  .** In the SQL s
10cd0 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20  trings input to 
10ce0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
10cf0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
10d00 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6f 6e 65 20  ariants,.** one 
10d10 6f 72 20 6d 6f 72 65 20 6c 69 74 65 72 61 6c 73  or more literals
10d20 20 63 61 6e 20 62 65 20 72 65 70 6c 61 63 65 20   can be replace 
10d30 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69  by a parameter i
10d40 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 0a 2a  n one of these.*
10d50 2a 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  * forms:.**.** <
10d60 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
10d70 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
10d80 3c 6c 69 3e 20 20 3a 41 41 41 0a 2a 2a 20 3c 6c  <li>  :AAA.** <l
10d90 69 3e 20 20 40 41 41 41 0a 2a 2a 20 3c 6c 69 3e  i>  @AAA.** <li>
10da0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
10db0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
10dc0 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
10dd0 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
10de0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
10df0 61 6c 2c 0a 2a 2a 20 41 41 41 20 69 73 20 61 6e  al,.** AAA is an
10e00 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
10e10 65 6e 74 69 66 69 65 72 20 61 6e 64 20 56 56 56  entifier and VVV
10e20 20 69 73 20 61 20 76 61 72 69 61 62 6c 65 20 6e   is a variable n
10e30 61 6d 65 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a  ame according.**
10e40 20 74 6f 20 74 68 65 20 73 79 6e 74 61 78 20 72   to the syntax r
10e50 75 6c 65 73 20 6f 66 20 74 68 65 20 54 43 4c 20  ules of the TCL 
10e60 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61 6e 67  programming lang
10e70 75 61 67 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  uage..** The val
10e80 75 65 73 20 6f 66 20 74 68 65 73 65 20 70 61 72  ues of these par
10e90 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
10ea0 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
10eb0 65 74 65 72 20 6e 61 6d 65 73 22 29 0a 2a 2a 20  eter names").** 
10ec0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
10ed0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
10ee0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
10ef0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
10f00 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
10f10 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
10f20 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
10f30 75 74 69 6e 65 73 20 61 6c 77 61 79 73 20 69 73  utines always is
10f40 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
10f50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
10f60 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
10f70 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
10f80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
10f90 6f 72 0a 2a 2a 20 69 74 73 20 76 61 72 69 61 6e  or.** its varian
10fa0 74 73 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a  ts.  The second.
10fb0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  ** argument is t
10fc0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
10fd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
10fe0 73 65 74 2e 20 20 54 68 65 20 66 69 72 73 74 20  set.  The first 
10ff0 70 61 72 61 6d 65 74 65 72 20 68 61 73 0a 2a 2a  parameter has.**
11000 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
11010 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
11020 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  med parameter is
11030 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
11040 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 0a 2a 2a 20  once, second.** 
11050 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
11060 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
11070 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
11080 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
11090 63 63 75 72 72 65 6e 63 65 2e 20 20 54 68 65 20  ccurrence.  The 
110a0 69 6e 64 65 78 20 66 6f 72 0a 2a 2a 20 6e 61 6d  index for.** nam
110b0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
110c0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
110d0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
110e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
110f0 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20  ter_name()] API 
11100 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65  if desired.  The
11110 20 69 6e 64 65 78 20 66 6f 72 20 22 3f 4e 4e 4e   index for "?NNN
11120 22 0a 2a 2a 20 70 61 72 61 6d 65 74 65 73 20 69  ".** parametes i
11130 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
11140 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76  NN..** The NNN v
11150 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
11160 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 63  ween 1 and the c
11170 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70  ompile-time.** p
11180 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45 5f  arameter SQLITE_
11190 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
111a0 42 45 52 20 28 64 65 66 61 75 6c 74 20 76 61 6c  BER (default val
111b0 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 20 53 65 65  ue: 999)..** See
111c0 20 3c 61 20 68 72 65 66 3d 22 6c 69 6d 69 74 73   <a href="limits
111d0 2e 68 74 6d 6c 22 3e 6c 69 6d 69 74 73 2e 68 74  .html">limits.ht
111e0 6d 6c 3c 2f 61 3e 20 66 6f 72 20 61 64 64 69 74  ml</a> for addit
111f0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
11200 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  n..**.** The thi
11210 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
11220 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
11230 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
11240 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73  r..**.** In thos
11250 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
11260 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
11270 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
11280 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62  alue is the numb
11290 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69  er of bytes.** i
112a0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
112b0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
112c0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  he value is the 
112d0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
112e0 69 6e 20 74 68 65 0a 2a 2a 20 73 74 72 69 6e 67  in the.** string
112f0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
11300 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 20   of characters. 
11310 20 54 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   The number.** o
11320 66 20 62 79 74 65 73 20 64 6f 65 73 20 6e 6f 74  f bytes does not
11330 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
11340 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o-terminator at 
11350 74 68 65 20 65 6e 64 20 6f 66 20 73 74 72 69 6e  the end of strin
11360 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  gs..** If the fo
11370 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
11380 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
11390 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
113a0 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75 6d 62 65  ring is.** numbe
113b0 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
113c0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
113d0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
113e0 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75  * The fifth argu
113f0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
11400 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
11410 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
11420 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
11430 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
11440 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
11450 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
11460 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
11470 20 74 65 78 74 20 61 66 74 65 72 20 53 51 4c 69   text after SQLi
11480 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
11490 77 69 74 68 20 69 74 2e 20 20 49 66 20 74 68 65  with it.  If the
114a0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
114b0 69 73 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 61  is the.** specia
114c0 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
114d0 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 74 68  STATIC], then th
114e0 65 20 6c 69 62 72 61 72 79 20 61 73 73 75 6d 65  e library assume
114f0 73 20 74 68 61 74 20 74 68 65 20 69 6e 66 6f 72  s that the infor
11500 6d 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 20  mation.** is in 
11510 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
11520 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
11530 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
11540 66 72 65 65 64 2e 20 20 49 66 20 74 68 65 0a 2a  freed.  If the.*
11550 2a 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  * fifth argument
11560 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
11570 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
11580 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ], then SQLite m
11590 61 6b 65 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20  akes its.** own 
115a0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
115b0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
115c0 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65  tely, before the
115d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
115e0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
115f0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
11600 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
11610 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
11620 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
11630 6c 65 6e 67 74 68 20 6e 20 74 68 61 74 0a 2a 2a  length n that.**
11640 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
11650 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c  zeros.  A zerobl
11660 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
11670 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
11680 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
11690 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20  eger to hold it 
116a0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
116b0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
116c0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
116d0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
116e0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d 68  serve as place-h
116f0 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
11700 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
11710 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
11720 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  en using .** [sq
11730 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
11740 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42  | increment BLOB
11750 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
11760 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11770 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
11780 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
11790 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c  ed after.** [sql
117a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
117b0 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69  )] (and its vari
117c0 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65  ants) or [sqlite
117d0 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a  3_reset()] and.*
117e0 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  * before [sqlite
117f0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69  3_step()]..** Bi
11800 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
11810 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
11820 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
11830 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f  routine..** Unbo
11840 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
11850 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
11860 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
11870 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
11880 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
11890 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
118a0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a   error code if.*
118b0 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  * anything goes 
118c0 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f  wrong.  [SQLITE_
118d0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
118e0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
118f0 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
11900 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b  out of range.  [
11910 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
11920 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
11930 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53  loc fails..** [S
11940 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 69 73  QLITE_MISUSE] is
11950 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
11960 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
11970 63 61 6c 6c 65 64 20 6f 6e 20 61 20 76 69 72 74  called on a virt
11980 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 74  ual.** machine t
11990 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67  hat is the wrong
119a0 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20   state or which 
119b0 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e  has already been
119c0 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f 0a 69   finalized..*/.i
119d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
119e0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
119f0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
11a00 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
11a10 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
11a20 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
11a30 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
11a40 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
11a50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
11a60 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
11a70 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
11a80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
11a90 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
11aa0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
11ab0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
11ac0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
11ad0 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
11ae0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
11af0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
11b00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
11b10 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
11b20 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
11b30 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
11b40 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
11b50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
11b60 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
11b70 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
11b80 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
11b90 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
11ba0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
11bb0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
11bc0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
11bd0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
11be0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
11bf0 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
11c00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
11c10 75 6d 62 65 72 20 4f 66 20 48 6f 73 74 20 50 61  umber Of Host Pa
11c20 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 52  rameters.**.** R
11c30 65 74 75 72 6e 20 74 68 65 20 6c 61 72 67 65 73  eturn the larges
11c40 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
11c50 20 69 6e 64 65 78 20 69 6e 20 74 68 65 20 70 72   index in the pr
11c60 65 63 6f 6d 70 69 6c 65 64 20 73 74 61 74 65 6d  ecompiled statem
11c70 65 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 61 73 20  ent given.** as 
11c80 74 68 65 20 61 72 67 75 6d 65 6e 74 2e 20 20 57  the argument.  W
11c90 68 65 6e 20 74 68 65 20 68 6f 73 74 20 70 61 72  hen the host par
11ca0 61 6d 65 74 65 72 73 20 61 72 65 20 6f 66 20 74  ameters are of t
11cb0 68 65 20 66 6f 72 6d 73 20 6c 69 6b 65 20 22 3a  he forms like ":
11cc0 41 41 41 22 0a 2a 2a 20 6f 72 20 22 3f 22 2c 20  AAA".** or "?", 
11cd0 74 68 65 6e 20 74 68 65 79 20 61 72 65 20 61 73  then they are as
11ce0 73 69 67 6e 65 64 20 73 65 71 75 65 6e 74 69 61  signed sequentia
11cf0 6c 20 69 6e 63 72 65 61 73 69 6e 67 20 6e 75 6d  l increasing num
11d00 62 65 72 73 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  bers beginning.*
11d10 2a 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f 20 74  * with one, so t
11d20 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
11d30 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
11d40 6f 66 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  of parameters.  
11d50 48 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20 74 68  However.** if th
11d60 65 20 73 61 6d 65 20 68 6f 73 74 20 70 61 72 61  e same host para
11d70 6d 65 74 65 72 20 6e 61 6d 65 20 69 73 20 75 73  meter name is us
11d80 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
11d90 73 2c 20 65 61 63 68 20 6f 63 63 75 72 72 61 6e  s, each occurran
11da0 63 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20 74  ce.** is given t
11db0 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 2c 20  he same number, 
11dc0 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  so the value ret
11dd0 75 72 6e 65 64 20 69 6e 20 74 68 61 74 20 63 61  urned in that ca
11de0 73 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  se is the number
11df0 0a 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20 68 6f  .** of unique ho
11e00 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
11e10 65 73 2e 20 20 49 66 20 68 6f 73 74 20 70 61 72  es.  If host par
11e20 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
11e30 6f 72 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 61 72  orm "?NNN".** ar
11e40 65 20 75 73 65 64 20 28 77 68 65 72 65 20 4e 4e  e used (where NN
11e50 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29  N is an integer)
11e60 20 74 68 65 6e 20 74 68 65 72 65 20 6d 69 67 68   then there migh
11e70 74 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  t be gaps in the
11e80 0a 2a 2a 20 6e 75 6d 62 65 72 69 6e 67 20 61 6e  .** numbering an
11e90 64 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  d the value retu
11ea0 72 6e 65 64 20 62 79 20 74 68 69 73 20 69 6e 74  rned by this int
11eb0 65 72 66 61 63 65 20 69 73 20 74 68 65 20 69 6e  erface is the in
11ec0 64 65 78 20 6f 66 20 74 68 65 0a 2a 2a 20 68 6f  dex of the.** ho
11ed0 73 74 20 70 61 72 61 6d 65 74 65 72 20 77 69 74  st parameter wit
11ee0 68 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e  h the largest in
11ef0 64 65 78 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  dex value..**.**
11f00 20 54 68 65 20 70 72 65 70 61 72 65 64 20 73 74   The prepared st
11f10 61 74 65 6d 65 6e 74 20 6d 75 73 74 20 6e 6f 74  atement must not
11f20 20 6e 6f 74 20 62 65 20 5b 73 71 6c 69 74 65 33   not be [sqlite3
11f30 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
11f40 6c 69 7a 65 64 5d 0a 2a 2a 20 70 72 69 6f 72 20  lized].** prior 
11f50 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
11f60 72 65 74 75 72 6e 6e 69 6e 67 2e 20 20 4f 74 68  returnning.  Oth
11f70 65 72 77 69 73 65 20 74 68 65 20 72 65 73 75 6c  erwise the resul
11f80 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
11f90 0a 2a 2a 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  .** and probably
11fa0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
11fb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
11fc0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
11fd0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
11fe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11ff0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
12000 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
12010 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
12020 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
12030 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   to the name of 
12040 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74  the n-th paramet
12050 65 72 20 69 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c  er in a .** [sql
12060 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
12070 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
12080 0a 2a 2a 20 48 6f 73 74 20 70 61 72 61 6d 65 74  .** Host paramet
12090 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
120a0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
120b0 20 6f 72 20 22 24 56 56 56 22 20 68 61 76 65 20   or "$VVV" have 
120c0 61 20 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20  a name.** which 
120d0 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3a  is the string ":
120e0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
120f0 72 20 22 24 56 56 56 22 2e 20 20 0a 2a 2a 20 49  r "$VVV".  .** I
12100 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
12110 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
12120 72 20 22 24 22 20 6f 72 20 22 40 22 0a 2a 2a 20  r "$" or "@".** 
12130 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
12140 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
12150 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f  .** Parameters o
12160 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 6f  f the form "?" o
12170 72 20 22 3f 4e 4e 4e 22 20 68 61 76 65 20 6e 6f  r "?NNN" have no
12180 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   name..**.** The
12190 20 66 69 72 73 74 20 62 6f 75 6e 64 20 70 61 72   first bound par
121a0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
121b0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
121c0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61  .**.** If the va
121d0 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20  lue n is out of 
121e0 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
121f0 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  n-th parameter i
12200 73 20 6e 61 6d 65 6c 65 73 73 2c 0a 2a 2a 20 74  s nameless,.** t
12210 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
12220 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  rned.  The retur
12230 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
12240 77 61 79 73 20 69 6e 20 74 68 65 0a 2a 2a 20 55  ways in the.** U
12250 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
12260 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
12270 70 61 72 61 6d 65 74 65 72 20 77 61 73 20 6f 72  parameter was or
12280 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
12290 65 64 0a 2a 2a 20 61 73 20 55 54 46 2d 31 36 20  ed.** as UTF-16 
122a0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
122b0 61 72 65 31 36 28 29 5d 20 6f 72 20 5b 73 71 6c  are16()] or [sql
122c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
122d0 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
122e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
122f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
12300 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
12310 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
12320 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
12330 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
12340 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
12350 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
12360 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
12370 65 78 20 6f 66 20 61 20 68 6f 73 74 20 70 61 72  ex of a host par
12380 61 6d 65 74 65 72 20 77 69 74 68 20 74 68 65 20  ameter with the 
12390 67 69 76 65 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  given name..** T
123a0 68 65 20 6e 61 6d 65 20 6d 75 73 74 20 6d 61 74  he name must mat
123b0 63 68 20 65 78 61 63 74 6c 79 2e 20 20 49 66 20  ch exactly.  If 
123c0 6e 6f 20 70 61 72 61 6d 65 74 65 72 20 77 69 74  no parameter wit
123d0 68 20 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65  h the given name
123e0 20 69 73 20 0a 2a 2a 20 66 6f 75 6e 64 2c 20 72   is .** found, r
123f0 65 74 75 72 6e 20 30 2e 20 20 50 61 72 61 6d 65  eturn 0.  Parame
12400 74 65 72 20 6e 61 6d 65 73 20 6d 75 73 74 20 62  ter names must b
12410 65 20 55 54 46 38 2e 0a 2a 2f 0a 69 6e 74 20 73  e UTF8..*/.int s
12420 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
12430 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
12440 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
12450 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
12460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12470 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
12480 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
12490 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
124a0 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65   Contrary to the
124b0 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
124c0 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
124d0 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a  et()] does not.*
124e0 2a 20 72 65 73 65 74 20 74 68 65 20 5b 73 71 6c  * reset the [sql
124f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
12500 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
12510 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
12520 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
12530 74 65 6d 65 6e 74 5d 2e 20 20 55 73 65 20 74 68  tement].  Use th
12540 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a  is routine to.**
12550 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
12560 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
12570 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
12580 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
12590 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
125a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
125b0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
125c0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
125d0 20 53 65 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72   Set.**.** Retur
125e0 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
125f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
12600 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
12610 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 73  ed by the .** [s
12620 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f  qlite3_stmt | co
12630 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
12640 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74  ment]. This rout
12650 69 6e 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a  ine returns 0.**
12660 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
12670 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
12680 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
12690 72 6e 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a  rn data (for .**
126a0 20 65 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41   example an UPDA
126b0 54 45 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  TE)..*/.int sqli
126c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
126d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
126e0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
126f0 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
12700 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
12710 20 53 65 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65   Set.**.** These
12720 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
12730 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
12740 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
12750 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
12760 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
12770 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  f a SELECT state
12780 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  ment.  The sqlit
12790 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
127a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
127b0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
127c0 74 6f 20 61 20 55 54 46 38 20 73 74 72 69 6e 67  to a UTF8 string
127d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
127e0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20  umn_name16().** 
127f0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
12800 72 20 74 6f 20 61 20 55 54 46 31 36 20 73 74 72  r to a UTF16 str
12810 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74 20  ing.  The first 
12820 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
12830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
12840 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
12850 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6d 70  tement] that imp
12860 6c 65 6d 65 6e 74 73 20 74 68 65 20 53 45 4c 45  lements the SELE
12870 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  CT statement..**
12880 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
12890 6d 65 74 65 72 20 69 73 20 74 68 65 20 63 6f 6c  meter is the col
128a0 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  umn number.  The
128b0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
128c0 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30  n is.** number 0
128d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75  ..**.** The retu
128e0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
128f0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
12900 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 0a 2a  il either the .*
12910 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
12920 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
12930 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
12940 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
12950 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72  inalize()].** or
12960 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
12970 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
12980 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
12990 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
129a0 65 31 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20  e16().** on the 
129b0 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
129c0 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
129d0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
129e0 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
129f0 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
12a00 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
12a10 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
12a20 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
12a30 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
12a40 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
12a50 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
12a60 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
12a70 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
12a80 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
12a90 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
12aa0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
12ab0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
12ac0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
12ad0 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
12ae0 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
12af0 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
12b00 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68   Result.**.** Th
12b10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
12b20 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
12b30 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63  determine what c
12b40 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a  olumn of what.**
12b50 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20   table in which 
12b60 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c  database a resul
12b70 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
12b80 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72  atement comes fr
12b90 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  om..** The name 
12ba0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
12bb0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
12bc0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
12bd0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
12be0 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20  a UTF8 or UTF16 
12bf0 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61  string.  The _da
12c00 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
12c10 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
12c20 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
12c30 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
12c40 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
12c50 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
12c60 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
12c70 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
12c80 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
12c90 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
12ca0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
12cb0 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  til.** the [sqli
12cc0 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61  te3_stmt | prepa
12cd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
12ce0 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e  s destroyed usin
12cf0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  g.** [sqlite3_fi
12d00 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
12d10 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
12d20 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
12d30 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
12d40 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
12d50 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oding..**.** The
12d60 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
12d70 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
12d80 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
12d90 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
12da0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
12db0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54   column..**.** T
12dc0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12dd0 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69  t to the followi
12de0 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 0a 2a  ng calls is a .*
12df0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
12e00 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  | compiled SQL s
12e10 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68  tatement]..** Th
12e20 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
12e30 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
12e40 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63   about the Nth c
12e50 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
12e60 79 20 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  y .** the statem
12e70 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
12e80 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
12e90 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
12ea0 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63  .** If the Nth c
12eb0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
12ec0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
12ed0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
12ee0 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65 72 79 20  .** or subquery 
12ef0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
12f00 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
12f10 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
12f20 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e  ctions.** return
12f30 20 4e 55 4c 4c 2e 20 4f 74 68 65 72 77 69 73 65   NULL. Otherwise
12f40 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
12f50 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  e .** name of th
12f60 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
12f70 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63  ase, table and c
12f80 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
12f90 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
12fa0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
12fb0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  from..**.** As w
12fc0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
12fd0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
12fe0 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20   postfixed with 
12ff0 22 31 36 22 20 72 65 74 75 72 6e 20 55 54 46 2d  "16" return UTF-
13000 31 36 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 73 74  16.** encoded st
13010 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72  rings, the other
13020 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
13030 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 54  n UTF-8..**.** T
13040 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
13050 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
13060 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
13070 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
13080 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41  e .** SQLITE_ENA
13090 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
130a0 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ATA preprocessor
130b0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
130c0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
130d0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
130e0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
130f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
13100 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
13110 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
13120 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
13130 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
13140 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
13150 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
13160 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
13170 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
13180 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
13190 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
131a0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
131b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
131c0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
131d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
131e0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
131f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
13200 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
13210 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
13220 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
13230 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
13240 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
13250 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
13260 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
13270 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
13280 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
13290 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
132a0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
132b0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
132c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
132d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
132e0 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
132f0 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
13300 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54  y Result.**.** T
13310 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
13320 65 72 20 69 73 20 61 20 5b 73 71 6c 69 74 65 33  er is a [sqlite3
13330 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
13340 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e   SQL statement].
13350 20 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61   .** If this sta
13360 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45  tement is a SELE
13370 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  CT statement and
13380 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
13390 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72  of the .** retur
133a0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 20  ned result set  
133b0 6f 66 20 74 68 61 74 20 53 45 4c 45 43 54 20 69  of that SELECT i
133c0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
133d0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
133e0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
133f0 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
13400 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
13410 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
13420 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49  n is returned. I
13430 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
13440 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
13450 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
13460 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
13470 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
13480 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
13490 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75  ned..** The retu
134a0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
134b0 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
134c0 64 65 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  ded. For example
134d0 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  , in.** the data
134e0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
134f0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
13500 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
13510 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f  **.** And the fo
13520 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
13530 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  t compiled:.**.*
13540 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
13550 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
13560 2a 2a 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75  ** Then this rou
13570 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
13580 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
13590 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
135a0 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20  econd.** result 
135b0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
135c0 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
135d0 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
135e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
135f0 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53   (i==0)..**.** S
13600 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
13610 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
13620 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63  ng.  So just bec
13630 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
13640 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
13650 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
13660 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
13670 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
13680 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
13690 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
136a0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
136b0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
136c0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
136d0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
136e0 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
136f0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70  not static.  Typ
13700 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
13710 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
13720 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
13730 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
13740 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
13750 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
13760 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
13770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
13780 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
13790 73 74 6d 74 20 2a 2c 20 69 6e 74 20 69 29 3b 0a  stmt *, int i);.
137a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
137b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
137c0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
137d0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a  mt*,int);../* .*
137e0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 76 61  * CAPI3REF:  Eva
137f0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
13800 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
13810 65 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73  er an [sqlite3_s
13820 74 6d 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d  tmt | SQL statem
13830 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
13840 65 70 61 72 65 64 20 77 69 74 68 20 61 20 63 61  epared with a ca
13850 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20  ll.** to either 
13860 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
13870 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
13880 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
13890 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a  )] or to one of.
138a0 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  ** the legacy in
138b0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
138c0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
138d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
138e0 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  16()],.** then t
138f0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  his function mus
13900 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
13910 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
13920 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a   evaluate the .*
13930 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  * statement..**.
13940 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
13950 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
13960 66 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73  f this sqlite3_s
13970 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
13980 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
13990 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
139a0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
139b0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
139c0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
139d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
139e0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
139f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
13a00 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
13a10 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
13a20 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
13a30 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
13a40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
13a50 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
13a60 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
13a70 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
13a80 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
13a90 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
13aa0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
13ab0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
13ac0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
13ad0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
13ae0 20 49 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69   In the lagacy i
13af0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
13b00 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
13b10 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
13b20 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51  E_BUSY], .** [SQ
13b30 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
13b40 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
13b50 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
13b60 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
13b70 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69   With the "v2" i
13b80 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
13b90 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49   the other [SQLI
13ba0 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
13bb0 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  ode].** or [SQLI
13bc0 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
13bd0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
13be0 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72  code] might be r
13bf0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65  eturned as.** we
13c00 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ll..**.** [SQLIT
13c10 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
13c20 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
13c30 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
13c40 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
13c50 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
13c60 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
13c70 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74  o its job.  If t
13c80 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
13c90 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f  a COMMIT.** or o
13ca0 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
13cb0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
13cc0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
13cd0 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
13ce0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
13cf0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
13d00 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54   is not a COMMIT
13d10 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
13d20 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74  in a.** explicit
13d30 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
13d40 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
13d50 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
13d60 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
13d70 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
13d80 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20  * [SQLITE_DONE] 
13d90 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
13da0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
13db0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
13dc0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
13dd0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
13de0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
13df0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
13e00 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
13e10 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
13e20 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
13e30 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
13e40 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
13e50 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
13e60 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
13e70 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
13e80 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
13e90 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
13ea0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
13eb0 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  data, then .** [
13ec0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72  SQLITE_ROW] is r
13ed0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
13ee0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
13ef0 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20  ata is ready.** 
13f00 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
13f10 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68  y the caller. Th
13f20 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
13f30 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a  accessed using.*
13f40 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
13f50 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75  olumn_int | colu
13f60 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
13f70 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
13f80 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
13f90 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
13fa0 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
13fb0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a   of data..** .**
13fc0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13fd0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
13fe0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
13ff0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
14000 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
14010 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
14020 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
14030 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
14040 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
14050 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
14060 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
14070 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
14080 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
14090 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  )]..** With the 
140a0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
140b0 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
140c0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78  c error code (ex
140d0 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54  ample:.** [SQLIT
140e0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
140f0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
14100 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
14110 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
14120 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
14130 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
14140 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
14150 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  n the.** [sqlite
14160 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  3_stmt | prepare
14170 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49  d statement].  I
14180 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
14190 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
141a0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
141b0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
141c0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
141d0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
141e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
141f0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
14200 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
14210 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
14220 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
14230 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
14240 6c 6c 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74  lled on a [sqlit
14250 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
14260 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
14270 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
14280 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
14290 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
142a0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
142b0 74 68 61 74 20 68 61 64 20 0a 2a 2a 20 70 72 65  that had .** pre
142c0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
142d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
142e0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
142f0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
14300 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
14310 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
14320 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14330 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
14340 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
14350 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
14360 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
14370 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  me..**.** <b>Goo
14380 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
14390 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68  rt:</b>.** In th
143a0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
143b0 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ce, .** the sqli
143c0 74 65 33 5f 73 74 65 70 28 29 20 41 50 49 20 61  te3_step() API a
143d0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
143e0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
143f0 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  de,.** [SQLITE_E
14400 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
14410 20 61 6e 79 20 65 72 72 6f 72 20 6f 74 68 65 72   any error other
14420 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
14430 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49  SY].** and [SQLI
14440 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
14450 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69   must call [sqli
14460 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
14470 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
14480 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
14490 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
144a0 74 68 65 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  the specific.** 
144b0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
144c0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 74 68  result codes] th
144d0 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
144e0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
144f0 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
14500 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
14510 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
14520 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
14530 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
14540 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
14550 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
14560 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
14570 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
14580 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
14590 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
145a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
145b0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
145c0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
145d0 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
145e0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
145f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
14600 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a  6()], then the .
14610 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  ** more specific
14620 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c   [SQLITE_ERROR |
14630 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
14640 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
14650 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
14660 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
14670 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
14680 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
14690 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
146a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
146b0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
146c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 0a 2a  *.** CAPI3REF:.*
146d0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
146e0 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73  number of values
146f0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
14700 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
14710 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  t set..**.** Aft
14720 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  er a call to [sq
14730 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 68  lite3_step()] th
14740 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  at returns [SQLI
14750 54 45 5f 52 4f 57 5d 2c 20 74 68 69 73 20 72 6f  TE_ROW], this ro
14760 75 74 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65  utine.** will re
14770 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61  turn the same va
14780 6c 75 65 20 61 73 20 74 68 65 20 5b 73 71 6c 69  lue as the [sqli
14790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
147a0 28 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ()] function..**
147b0 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   After [sqlite3_
147c0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
147d0 72 6e 65 64 20 61 6e 20 5b 53 51 4c 49 54 45 5f  rned an [SQLITE_
147e0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  DONE], [SQLITE_B
147f0 55 53 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53  USY], or.** a [S
14800 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72  QLITE_ERROR | er
14810 72 6f 72 20 63 6f 64 65 5d 2c 20 6f 72 20 62 65  ror code], or be
14820 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  fore [sqlite3_st
14830 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 0a  ep()] has been .
14840 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  ** called on the
14850 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
14860 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
14870 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72  ent] for the fir
14880 73 74 20 74 69 6d 65 2c 0a 2a 2a 20 74 68 69 73  st time,.** this
14890 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
148a0 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71   zero..*/.int sq
148b0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
148c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
148d0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
148e0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
148f0 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
14900 0a 2a 2a 20 45 76 65 72 79 20 76 61 6c 75 65 20  .** Every value 
14910 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
14920 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
14930 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
14940 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
14950 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
14960 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
14970 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
14980 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
14990 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
149a0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
149b0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
149c0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  </ul>.**.** Thes
149d0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
149e0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
149f0 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
14a00 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
14a10 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
14a20 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
14a30 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
14a40 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
14a50 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
14a60 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
14a70 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
14a80 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
14a90 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
14aa0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
14ab0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
14ac0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
14ad0 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  EXT not.** SQLIT
14ae0 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
14af0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
14b00 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
14b10 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
14b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
14b30 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
14b40 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
14b50 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
14b60 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
14b70 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
14b80 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
14b90 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
14ba0 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
14bb0 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
14bc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
14bd0 73 75 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f  sults Values Fro
14be0 6d 20 41 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  m A Query.**.** 
14bf0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
14c00 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
14c10 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e  n about.** a sin
14c20 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
14c30 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74  e current result
14c40 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
14c50 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61    In every.** ca
14c60 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
14c70 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
14c80 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73  er to the .** [s
14c90 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51  qlite3_stmt | SQ
14ca0 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  L statement] tha
14cb0 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76  t is being.** ev
14cc0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
14cd0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61  lite3_stmt*] tha
14ce0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
14cf0 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
14d00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
14d10 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
14d20 69 61 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68  iants) and.** th
14d30 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
14d40 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
14d50 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
14d60 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
14d70 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  on .** should be
14d80 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
14d90 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
14da0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
14db0 65 74 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e 64  et.** has an ind
14dc0 65 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49  ex of 0..**.** I
14dd0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
14de0 65 6e 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ent is not curre
14df0 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
14e00 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
14e10 20 74 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75   the.** the colu
14e20 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
14e30 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
14e40 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
14e50 64 2e 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  d. .** These rou
14e60 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
14e70 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
14e80 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
14e90 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
14ea0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
14eb0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
14ec0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
14ed0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
14ee0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
14ef0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
14f00 73 20 62 65 65 6e 20 63 61 6c 6c 20 73 75 62 73  s been call subs
14f10 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
14f20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
14f30 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
14f40 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
14f50 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
14f60 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
14f70 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
14f80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
14f90 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
14fa0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
14fb0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
14fc0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
14fd0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
14fe0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
14ff0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
15000 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
15010 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
15020 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
15030 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
15040 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
15050 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
15060 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
15070 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
15080 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
15090 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .  .**.** The sq
150a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
150b0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
150c0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
150d0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
150e0 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
150f0 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
15100 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
15110 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65  ult column.  The
15120 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
15130 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
15140 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
15150 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
15160 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
15170 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
15180 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
15190 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
151a0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
151b0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
151c0 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
151d0 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
151e0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
151f0 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
15200 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
15210 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
15220 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
15230 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
15240 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
15250 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
15260 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
15270 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
15280 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
15290 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
152a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
152b0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
152c0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
152d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
152e0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
152f0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
15300 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
15310 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
15320 29 20 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ) .** routine re
15330 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
15340 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
15350 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
15360 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
15370 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
15380 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
15390 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
153a0 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
153b0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
153c0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
153d0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
153e0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74  f bytes..** If t
153f0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
15400 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
15410 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
15420 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
15430 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
15440 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
15450 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
15460 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
15470 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
15480 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
15490 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
154a0 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65  .** The value re
154b0 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
154c0 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
154d0 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74   terminator at t
154e0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
154f0 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c   string.  For cl
15500 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
15510 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65   returned is the
15520 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
15530 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
15540 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
15550 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
15560 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
15570 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
15580 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  6() routine is s
15590 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65  imilar to sqlite
155a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
155b0 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74  .** but leaves t
155c0 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46  he result in UTF
155d0 2d 31 36 20 69 6e 73 74 65 61 64 20 6f 66 20 55  -16 instead of U
155e0 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a  TF-8.  .** The z
155f0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
15600 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
15610 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a  n this count..**
15620 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
15630 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
15640 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
15650 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
15660 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
15670 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
15680 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
15690 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
156a0 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
156b0 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
156c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
156d0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
156e0 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65  rnally to do the
156f0 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61   conversion.** a
15700 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
15710 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
15720 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
15730 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68 61 74 0a  onversions that.
15740 2a 2a 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  ** are applied:.
15750 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15760 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
15770 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
15780 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 20 3c 74  <th> Internal <t
15790 68 3e 20 52 65 71 75 65 73 74 65 64 20 3c 74 68  h> Requested <th
157a0 3e 20 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 20  > .** <tr><th>  
157b0 54 79 70 65 20 20 20 20 3c 74 68 3e 20 20 20 20  Type    <th>    
157c0 54 79 70 65 20 20 20 3c 74 68 3e 20 43 6f 6e 76  Type   <th> Conv
157d0 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
157e0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
157f0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
15800 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
15810 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
15820 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
15830 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
15840 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
15850 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
15860 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
15870 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
15880 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
15890 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
158a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
158b0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
158c0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
158d0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
158e0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
158f0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
15900 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
15910 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
15920 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
15930 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
15940 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
15950 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
15960 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
15970 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
15980 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45 47 45  me as for INTEGE
15990 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
159a0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
159b0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
159c0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
159d0 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
159e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
159f0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
15a00 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
15a10 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
15a20 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
15a30 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
15a40 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
15a50 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
15a60 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
15a70 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
15a80 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
15a90 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
15aa0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
15ab0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
15ac0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
15ad0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
15ae0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
15af0 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
15b00 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
15b10 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
15b20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
15b30 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
15b40 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
15b50 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
15b60 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
15b70 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
15b80 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
15b90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
15ba0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
15bb0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
15bc0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
15bd0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
15be0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
15bf0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ote>.**.** The t
15c00 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
15c10 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
15c20 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
15c30 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
15c40 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
15c50 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
15c60 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
15c70 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
15c80 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20  t has its.** on 
15c90 65 71 75 61 76 61 6c 65 6e 74 20 69 6e 74 65 72  equavalent inter
15ca0 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
15cb0 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
15cc0 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
15cd0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
15ce0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
15cf0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
15d00 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
15d10 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
15d20 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
15d30 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
15d40 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
15d50 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
15d60 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
15d70 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
15d80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
15d90 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
15da0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
15db0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
15dc0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
15dd0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20  be invalidated. 
15de0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
15df0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
15e00 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
15e10 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
15e20 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
15e30 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
15e40 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
15e50 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
15e60 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
15e70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
15e80 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  xt() .**        
15e90 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c    or sqlite3_col
15ea0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
15eb0 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
15ec0 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
15ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 65  .**          nee
15ee0 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
15ef0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e   the string.</p>
15f00 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
15f10 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c  <p>  The initial
15f20 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
15f30 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
15f40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
15f50 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  6() or.**       
15f60 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
15f70 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
15f80 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
15f90 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
15fa0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rted.**         
15fb0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c   to UTF-16.</p><
15fc0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c  /li>.**.** <li><
15fd0 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20  p>  The initial 
15fe0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
15ff0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
16000 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
16010 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ) or.**         
16020 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
16030 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
16040 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
16050 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
16060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
16070 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a  UTF-8.</p></li>.
16080 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43  ** </ul>.**.** C
16090 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
160a0 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
160b0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
160c0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
160d0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
160e0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
160f0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
16100 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
16110 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
16120 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
16130 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
16140 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20   points to will 
16150 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
16160 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
16170 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
16180 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
16190 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
161a0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
161b0 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e  etime it is.** n
161c0 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
161d0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
161e0 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
161f0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 20  e invalidated.  
16200 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
16210 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
16220 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
16230 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
16240 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
16250 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
16260 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
16270 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  .**  <ul>.**  <l
16280 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
16290 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
162a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
162b0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
162c0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
162d0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
162e0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
162f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
16300 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
16310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
16320 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
16330 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
16340 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
16350 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  **  </ul>.**.** 
16360 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
16370 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
16380 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
16390 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  ext(), sqlite3_c
163a0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  olumn_blob(),.**
163b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
163c0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
163d0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
163e0 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65 20 64  esult into the d
163f0 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74  esired.** format
16400 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
16410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
16420 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  es() or sqlite3_
16430 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
16440 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20   to.** find the 
16450 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
16460 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
16470 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
16480 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
16490 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
164a0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
164b0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
164c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
164d0 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a  .  And do not.**
164e0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
164f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
16500 74 31 36 28 29 20 77 69 74 68 20 63 61 6c 6c 73  t16() with calls
16510 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
16520 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
16530 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72  * The pointers r
16540 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
16550 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
16560 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
16570 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
16580 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
16590 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
165a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
165b0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
165c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
165d0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ] is called.  Th
165e0 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
165f0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
16600 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73  ngs.** and blobs
16610 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
16620 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
16630 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
16640 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
16650 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
16660 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
16670 73 71 6c 69 74 65 5f 63 6f 6c 75 6d 6e 5f 74 65  sqlite_column_te
16680 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
16690 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72   .** [sqlite3_fr
166a0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ee()]..**.** If 
166b0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
166c0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
166d0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
166e0 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
166f0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
16700 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
16710 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
16720 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
16730 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
16740 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
16750 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
16760 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
16770 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
16780 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
16790 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
167a0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
167b0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
167c0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a  LITE_NOMEM]..*/.
167d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
167e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
167f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
16800 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
16810 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
16820 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
16830 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
16840 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
16850 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
16860 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
16870 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
16880 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
16890 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
168a0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
168b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
168c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
168d0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
168e0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
168f0 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
16900 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
16910 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
16920 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
16930 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
16940 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
16950 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
16960 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
16970 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
16980 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
16990 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
169a0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
169b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
169c0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
169d0 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
169e0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
169f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
16a00 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
16a10 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
16a20 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
16a30 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
16a40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e   The sqlite3_fin
16a50 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
16a60 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
16a70 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 73 71 6c 69  lete a .** [sqli
16a80 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69  te3_stmt | compi
16a90 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
16aa0 74 5d 2e 20 49 66 20 74 68 65 20 73 74 61 74 65  t]. If the state
16ab0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65 63  ment was.** exec
16ac0 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  uted successfull
16ad0 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74  y, or not execut
16ae0 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20  ed at all, then 
16af0 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
16b00 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65  urned..** If exe
16b10 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  cution of the st
16b20 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74  atement failed t
16b30 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49  hen an .** [SQLI
16b40 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72  TE_ERROR | error
16b50 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54   code] or [SQLIT
16b60 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
16b70 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
16b80 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  de].** is return
16b90 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ed. .**.** This 
16ba0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
16bb0 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
16bc0 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78  nt during the ex
16bd0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ecution of the.*
16be0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
16bf0 7c 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  | virtual machin
16c00 65 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74  e].  If the virt
16c10 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20  ual machine has 
16c20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  not .** complete
16c30 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e  d execution when
16c40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
16c50 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73   called, that is
16c60 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74   like.** encount
16c70 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f  ering an error o
16c80 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e 20  r an interrupt. 
16c90 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 69   (See [sqlite3_i
16ca0 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a  nterrupt()].) .*
16cb0 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64  * Incomplete upd
16cc0 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c  ates may be roll
16cd0 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e  ed back and tran
16ce0 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c  sactions cancell
16cf0 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69  ed,  .** dependi
16d00 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
16d10 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
16d20 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
16d30 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OR | result code
16d40 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20  ] returned will 
16d50 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  be [SQLITE_ABORT
16d60 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
16d70 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
16d80 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
16d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16da0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
16db0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
16dc0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ect.**.** The sq
16dd0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
16de0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
16df0 20 74 6f 20 72 65 73 65 74 20 61 20 0a 2a 2a 20   to reset a .** 
16e00 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
16e10 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
16e20 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a  tement] object..
16e30 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 27 73 20  ** back to it's 
16e40 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
16e50 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
16e60 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53  ecuted..** Any S
16e70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
16e80 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
16e90 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
16ea0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
16eb0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
16ec0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
16ed0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
16ee0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
16ef0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
16f00 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
16f10 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
16f20 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 69 6e   bindings..*/.in
16f30 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
16f40 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
16f50 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
16f60 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
16f70 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
16f80 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
16f90 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
16fa0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
16fb0 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
16fc0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
16fd0 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72  gates.** or to r
16fe0 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
16ff0 76 69 6f 72 20 6f 66 20 65 78 69 73 74 69 6e 67  vior of existing
17000 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
17010 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
17020 68 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65  he.** difference
17030 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20 74 68   only between th
17040 65 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68  e two is that th
17050 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17060 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20  er, the.** name 
17070 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20  of the (scalar) 
17080 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
17090 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65  egate, is encode
170a0 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d in UTF-8 for.*
170b0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
170c0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20  _function() and 
170d0 55 54 46 2d 31 36 20 66 6f 72 20 73 71 6c 69 74  UTF-16 for sqlit
170e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
170f0 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
17100 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17110 20 69 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33   is the [sqlite3
17120 20 7c 20 64 61 74 61 62 61 73 65 20 68 61 6e 64   | database hand
17130 6c 65 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 74  le] that holds t
17140 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
17150 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 20  on or aggregate 
17160 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 20 6f  is to be added o
17170 72 20 72 65 64 65 66 69 6e 65 64 2e 20 49 66 20  r redefined. If 
17180 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67  a single.** prog
17190 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ram uses more th
171a0 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 20  an one database 
171b0 68 61 6e 64 6c 65 20 69 6e 74 65 72 6e 61 6c 6c  handle internall
171c0 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66  y, then SQL.** f
171d0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
171e0 65 67 61 74 65 73 20 6d 75 73 74 20 62 65 20 61  egates must be a
171f0 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  dded individuall
17200 79 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  y to each databa
17210 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20 77 69 74  se.** handle wit
17220 68 20 77 68 69 63 68 20 74 68 65 79 20 77 69 6c  h which they wil
17230 6c 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  l be used..**.**
17240 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17250 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
17260 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
17270 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
17280 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69  ted.** or redefi
17290 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67  ned..** The leng
172a0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
172b0 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
172c0 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76   bytes, exclusiv
172d0 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72  e of the .** zer
172e0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e  o-terminator.  N
172f0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
17300 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  e length limit i
17310 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a  s in bytes, not.
17320 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20  ** characters.  
17330 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
17340 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
17350 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
17360 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
17370 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f  lt in an SQLITE_
17380 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a  ERROR error..**.
17390 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72  ** The third par
173a0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 75  ameter is the nu
173b0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
173c0 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
173d0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
173e0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49  gregate takes. I
173f0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
17400 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
17410 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
17420 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
17430 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
17440 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
17450 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
17460 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
17470 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
17480 69 66 69 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b  ifies what .** [
17490 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
174a0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
174b0 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
174c0 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
174d0 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41  s parameters.  A
174e0 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ny SQL function 
174f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
17500 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f  hould be able to
17510 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69   work.** work wi
17520 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
17530 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
17540 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
17550 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
17560 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
17570 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
17580 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
17590 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77  er.  It is allow
175a0 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
175b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
175c0 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
175d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
175e0 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
175f0 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
17600 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
17610 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
17620 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
17630 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e  TextRep..** When
17640 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
17650 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
17660 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
17670 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
17680 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
17690 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
176a0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
176b0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
176c0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
176d0 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
176e0 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
176f0 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
17700 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
17710 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  t.** text encodi
17720 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
17730 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
17740 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ment should be.*
17750 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  * [SQLITE_ANY]..
17760 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
17770 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
17780 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
17790 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
177a0 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
177b0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
177c0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
177d0 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a  s pointer using.
177e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ** [sqlite3_user
177f0 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _data()]..**.** 
17800 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67  The seventh, eig
17810 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61  hth and ninth pa
17820 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
17830 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
17840 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
17850 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
17860 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
17870 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
17880 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72  L.** function or
17890 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63   aggregate. A sc
178a0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
178b0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
178c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a  plementation of.
178d0 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 63 61 6c  ** the xFunc cal
178e0 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c  lback only, NULL
178f0 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64   pointers should
17900 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
17910 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  e xStep.** and x
17920 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  Final parameters
17930 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53  . An aggregate S
17940 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
17950 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
17960 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74  tation.** of xSt
17970 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ep and xFinal an
17980 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65  d NULL should be
17990 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
179a0 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a  c. To delete an.
179b0 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  ** existing SQL 
179c0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
179d0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
179e0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
179f0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
17a00 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ack..**.** It is
17a10 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
17a20 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
17a30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
17a40 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
17a50 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
17a60 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
17a70 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
17a80 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
17a90 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
17aa0 20 64 69 66 66 65 72 69 6e 67 20 70 65 72 66 65   differing perfe
17ab0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
17ac0 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ngs.  SQLite wil
17ad0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
17ae0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74  lementation most
17af0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
17b00 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
17b10 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
17b20 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ction is used..*
17b30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
17b40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
17b50 20 73 71 6c 69 74 65 33 20 2a 2c 0a 20 20 63 6f   sqlite3 *,.  co
17b60 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
17b70 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
17b80 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
17b90 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  Rep,.  void*,.  
17ba0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
17bb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
17bc0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
17bd0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
17be0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
17bf0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
17c00 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
17c10 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
17c20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
17c30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
17c40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
17c50 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63  .  sqlite3*,.  c
17c60 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
17c70 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
17c80 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
17c90 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20  tRep,.  void*,. 
17ca0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
17cb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
17cc0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
17cd0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
17ce0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
17cf0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
17d00 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
17d10 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
17d20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
17d30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17d40 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
17d50 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
17d60 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
17d70 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
17d80 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
17d90 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
17da0 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
17db0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
17dc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17dd0 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
17de0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
17df0 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
17e00 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
17e10 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
17e20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
17e30 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
17e40 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
17e50 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
17e60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17e70 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
17e80 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
17e90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
17ea0 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
17eb0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
17ec0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
17ed0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
17ee0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
17ef0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
17f00 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e  bsolete Function
17f10 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  s.**.** These fu
17f20 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20  nctions are all 
17f30 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49  now obsolete.  I
17f40 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
17f50 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
17f60 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
17f70 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
17f80 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73  we continue to s
17f90 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20  upport.** these 
17fa0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65  functions.  Howe
17fb0 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70  ver, new develop
17fc0 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68  ment projects sh
17fd0 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
17fe0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
17ff0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
18000 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
18010 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
18020 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
18030 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
18040 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
18050 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f  you want they do
18060 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18070 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
18080 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
18090 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
180a0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
180b0 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  stmt*);.int sqli
180c0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
180d0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
180e0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
180f0 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
18100 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
18110 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69  void);.void sqli
18120 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
18130 75 70 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  up(void);../*.**
18140 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
18150 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
18160 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
18170 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
18180 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
18190 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
181a0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
181b0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
181c0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
181d0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
181e0 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
181f0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
18200 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
18210 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
18220 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
18230 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
18240 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
18250 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
18260 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
18270 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
18280 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
18290 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
182a0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
182b0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
182c0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
182d0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
182e0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
182f0 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
18300 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
18310 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
18320 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
18330 72 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  rs to.** [sqlite
18340 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
18350 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
18360 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
18370 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
18380 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
18390 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
183a0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
183b0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
183c0 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
183d0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
183e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
183f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
18400 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
18410 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
18420 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  ponding .** [sql
18430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
18440 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
18450 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 78  n_* routines] ex
18460 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68  cept that .** th
18470 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
18480 65 20 61 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69  e a single [sqli
18490 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e  te3_value*] poin
184a0 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ter instead.** o
184b0 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  f an [sqlite3_st
184c0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
184d0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
184e0 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
184f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
18500 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
18510 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
18520 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a   UTF16 string.**
18530 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
18540 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
18550 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
18560 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
18570 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
18580 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
18590 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
185a0 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
185b0 63 74 20 55 54 46 31 36 20 73 74 72 69 6e 67 73  ct UTF16 strings
185c0 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
185d0 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
185e0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
185f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
18600 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
18610 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
18620 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
18630 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
18640 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
18650 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
18660 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
18670 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
18680 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
18690 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
186a0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
186b0 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
186c0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
186d0 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
186e0 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
186f0 6e 20 28 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 77  n (in order.** w
18700 6f 72 64 73 20 69 66 20 74 68 65 20 76 61 6c 75  ords if the valu
18710 65 20 69 73 20 6f 72 69 67 69 6e 61 6c 20 61 20  e is original a 
18720 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
18730 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
18740 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
18750 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73 65 20  one.  Otherwise 
18760 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
18770 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b  curs.  The .** [
18780 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
18790 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
187a0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
187b0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  eturned..**.** P
187c0 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
187d0 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
187e0 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
187f0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
18800 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
18810 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
18820 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
18830 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
18840 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
18850 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
18860 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
18870 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
18880 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
18890 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
188a0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
188b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
188c0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
188d0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
188e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
188f0 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20 20 0a  ue_text16()].  .
18900 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
18910 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
18920 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
18930 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
18940 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
18950 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
18960 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e sqlite3_value*
18970 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 20   parameters..** 
18980 4f 72 2c 20 69 66 20 74 68 65 20 73 71 6c 69 74  Or, if the sqlit
18990 65 33 5f 76 61 6c 75 65 2a 20 61 72 67 75 6d 65  e3_value* argume
189a0 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68  nt comes from th
189b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
189c0 6e 5f 76 61 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e  n_value()].** in
189d0 74 65 72 66 61 63 65 2c 20 74 68 65 6e 20 74 68  terface, then th
189e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  ese routines sho
189f0 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 66 72  uld be called fr
18a00 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
18a10 61 64 0a 2a 2a 20 74 68 61 74 20 72 61 6e 20 5b  ad.** that ran [
18a20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
18a30 61 6c 75 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  alue()]..*/.cons
18a40 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
18a50 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
18a60 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
18a70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
18a80 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
18a90 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
18aa0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
18ab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
18ac0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
18ad0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
18ae0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
18af0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
18b00 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
18b10 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
18b20 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
18b30 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
18b40 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
18b50 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
18b60 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
18b70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
18b80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
18b90 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
18ba0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
18bb0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
18bc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
18bd0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
18be0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
18bf0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
18c00 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
18c10 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
18c20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
18c30 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
18c40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
18c50 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
18c60 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
18c70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18c80 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
18c90 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
18ca0 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  text.**.** The i
18cb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
18cc0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
18cd0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
18ce0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  s routine to all
18cf0 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63  ocate.** a struc
18d00 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67  ture for storing
18d10 20 74 68 65 69 72 20 73 74 61 74 65 2e 20 20 54   their state.  T
18d20 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
18d30 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73  is routine.** is
18d40 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20 70 61   called for a pa
18d50 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
18d60 74 65 2c 20 61 20 6e 65 77 20 73 74 72 75 63 74  te, a new struct
18d70 75 72 65 20 6f 66 20 73 69 7a 65 20 6e 42 79 74  ure of size nByt
18d80 65 73 0a 2a 2a 20 69 73 20 61 6c 6c 6f 63 61 74  es.** is allocat
18d90 65 64 2c 20 7a 65 72 6f 65 64 2c 20 61 6e 64 20  ed, zeroed, and 
18da0 72 65 74 75 72 6e 65 64 2e 20 20 4f 6e 20 73 75  returned.  On su
18db0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 28  bsequent calls (
18dc0 66 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20  for the.** same 
18dd0 61 67 67 72 65 67 61 74 65 20 69 6e 73 74 61 6e  aggregate instan
18de0 63 65 29 20 74 68 65 20 73 61 6d 65 20 62 75 66  ce) the same buf
18df0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
18e00 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
18e10 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61  tion.** of the a
18e20 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65  ggregate can use
18e30 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75   the returned bu
18e40 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61  ffer to accumula
18e50 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 54  te data..**.** T
18e60 68 65 20 62 75 66 66 65 72 20 61 6c 6c 6f 63 61  he buffer alloca
18e70 74 65 64 20 69 73 20 66 72 65 65 64 20 61 75 74  ted is freed aut
18e80 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 53 51  omatically by SQ
18e90 4c 69 74 65 20 77 68 61 6e 20 74 68 65 20 61 67  Lite whan the ag
18ea0 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79  gregate.** query
18eb0 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
18ec0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
18ed0 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
18ee0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a  a copy of the .*
18ef0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
18f00 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
18f10 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
18f20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
18f30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
18f40 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
18f50 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
18f60 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
18f70 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
18f80 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
18f90 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
18fa0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
18fb0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
18fc0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
18fd0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
18fe0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
18ff0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
19000 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
19010 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
19020 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
19030 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
19040 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
19050 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 55 73 65  s.**.** The pUse
19060 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
19070 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
19080 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
19090 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
190a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
190b0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
190c0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 72 65 67 69  .** used to regi
190d0 73 74 65 72 20 75 73 65 72 20 66 75 6e 63 74 69  ster user functi
190e0 6f 6e 73 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ons is available
190f0 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65   to.** the imple
19100 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
19110 20 66 75 6e 63 74 69 6f 6e 20 75 73 69 6e 67 20   function using 
19120 74 68 69 73 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  this call..**.**
19130 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
19140 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
19150 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
19160 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
19170 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
19180 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
19190 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
191a0 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
191b0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
191c0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
191d0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
191e0 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  a.**.** The foll
191f0 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
19200 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
19210 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
19220 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
19230 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74  sociate meta-dat
19240 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
19250 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
19260 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
19270 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
19280 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
19290 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
192a0 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
192b0 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
192c0 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
192d0 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
192e0 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 2d  associated meta-
192f0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
19300 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
19310 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
19320 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
19330 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
19340 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
19350 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
19360 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
19370 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
19380 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
19390 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
193a0 20 6d 65 74 61 2d 64 61 74 61 20 61 73 73 6f 63   meta-data assoc
193b0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
193c0 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
193d0 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
193e0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
193f0 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
19400 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
19410 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
19420 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
19430 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
19440 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
19450 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
19460 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
19470 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
19480 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
19490 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
194a0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
194b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
194c0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
194d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
194e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
194f0 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61  e meta-data.** a
19500 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
19510 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
19520 76 61 6c 75 65 20 74 6f 20 74 68 65 20 63 75 72  value to the cur
19530 72 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  rent SQL functio
19540 6e 0a 2a 2a 20 63 61 6c 6c 2c 20 77 68 65 72 65  n.** call, where
19550 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
19560 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 6e   parameter. If n
19570 6f 20 6d 65 74 61 2d 64 61 74 61 20 68 61 73 20  o meta-data has 
19580 62 65 65 6e 20 73 65 74 20 66 6f 72 0a 2a 2a 20  been set for.** 
19590 74 68 61 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  that value, then
195a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
195b0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
195c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
195d0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20  et_auxdata() is 
195e0 75 73 65 64 20 74 6f 20 61 73 73 6f 63 69 61 74  used to associat
195f0 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68  e meta-data with
19600 20 61 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74   an SQL.** funct
19610 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 20 54 68  ion argument. Th
19620 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
19630 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
19640 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a  o the meta-data.
19650 2a 2a 20 74 6f 20 62 65 20 61 73 73 6f 63 69 61  ** to be associa
19660 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68  ted with the Nth
19670 20 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 20 61   user function a
19680 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 2e 20 54  rgument value. T
19690 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72  he fourth.** par
196a0 61 6d 65 74 65 72 20 73 70 65 63 69 66 69 65 73  ameter specifies
196b0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 74 68   a destructor th
196c0 61 74 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  at will be calle
196d0 64 20 6f 6e 20 74 68 65 20 6d 65 74 61 2d 0a 2a  d on the meta-.*
196e0 2a 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  * data pointer t
196f0 6f 20 72 65 6c 65 61 73 65 20 69 74 20 77 68 65  o release it whe
19700 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
19710 72 20 72 65 71 75 69 72 65 64 2e 20 49 66 20 74  r required. If t
19720 68 65 20 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  he .** destructo
19730 72 20 69 73 20 4e 55 4c 4c 2c 20 69 74 20 69 73  r is NULL, it is
19740 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a   not invoked..**
19750 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c  .** In practice,
19760 20 6d 65 74 61 2d 64 61 74 61 20 69 73 20 70 72   meta-data is pr
19770 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
19780 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
19790 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
197a0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
197b0 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
197c0 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
197d0 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
197e0 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72  lues and SQL var
197f0 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  iables..**.** Th
19800 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
19810 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
19820 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
19830 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
19840 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
19850 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
19860 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
19870 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
19880 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
19890 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
198a0 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
198b0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 2c 20 76  context*, int, v
198c0 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
198d0 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
198e0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
198f0 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
19900 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
19910 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
19920 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
19930 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 64   value for the d
19940 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
19950 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
19960 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
19970 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
19980 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
19990 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
199a0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
199b0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
199c0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
199d0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
199e0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
199f0 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
19a00 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
19a10 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
19a20 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
19a30 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 20  destroyed.  The 
19a40 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
19a50 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
19a60 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
19a70 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
19a80 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
19a90 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
19aa0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
19ab0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
19ac0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
19ad0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
19ae0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
19af0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
19b00 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
19b10 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
19b20 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
19b30 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
19b40 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
19b50 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
19b60 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
19b70 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
19b80 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
19b90 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
19ba0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
19bb0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
19bc0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
19bd0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
19be0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
19bf0 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
19c00 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
19c10 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
19c20 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
19c30 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
19c40 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
19c50 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
19c60 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
19c70 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
19c80 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
19c90 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
19ca0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
19cb0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
19cc0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
19cd0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
19ce0 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
19cf0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
19d00 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
19d10 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
19d20 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
19d30 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
19d40 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
19d50 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d  ite3_bind_*] fam
19d60 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
19d70 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64   used.** to bind
19d80 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
19d90 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
19da0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
19db0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
19dc0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
19dd0 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
19de0 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65  e3_bind_* docume
19df0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20  ntation] for.** 
19e00 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
19e10 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
19e20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
19e30 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
19e40 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
19e50 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
19e60 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
19e70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
19e80 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
19e90 6e 20 65 78 63 65 70 74 69 6f 6e 2e 20 20 54 68  n exception.  Th
19ea0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  e.** parameter t
19eb0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
19ec0 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
19ed0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
19ee0 31 36 28 29 0a 2a 2a 20 69 73 20 74 68 65 20 74  16().** is the t
19ef0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
19f00 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 54  message..**.** T
19f10 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
19f20 74 5f 74 6f 6f 62 69 67 28 29 20 63 61 75 73 65  t_toobig() cause
19f30 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
19f40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
19f50 74 6f 20 74 68 72 6f 77 20 61 6e 64 20 65 72 72  to throw and err
19f60 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
19f70 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
19f80 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a  LOB is to long.*
19f90 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  * to represent..
19fa0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
19fb0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
19fc0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
19fd0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
19fe0 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
19ff0 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65  nction associate
1a000 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  d with the [sqli
1a010 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
1a020 6e 74 65 72 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  nter..*/.void sq
1a030 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
1a040 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
1a050 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
1a060 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
1a070 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
1a080 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
1a090 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
1a0a0 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
1a0b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1a0c0 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
1a0d0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
1a0e0 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
1a0f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1a100 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
1a110 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
1a120 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
1a130 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1a140 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
1a150 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
1a160 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1a170 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
1a180 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
1a190 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1a1a0 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
1a1b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
1a1c0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
1a1d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1a1e0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
1a1f0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
1a200 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
1a210 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
1a220 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
1a230 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
1a240 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
1a250 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
1a260 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
1a270 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
1a280 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
1a290 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
1a2a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
1a2b0 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
1a2c0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
1a2d0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
1a2e0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
1a2f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
1a300 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
1a310 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
1a320 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
1a330 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
1a340 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
1a350 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
1a360 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
1a370 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
1a380 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
1a390 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
1a3a0 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
1a3b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1a3c0 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
1a3d0 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
1a3e0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
1a3f0 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
1a400 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  dd new collation
1a410 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68   sequences to th
1a420 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20  e.** [sqlite3*] 
1a430 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64  handle specified
1a440 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
1a450 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54  gument. .**.** T
1a460 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
1a470 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
1a480 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69  uence is specifi
1a490 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74  ed as a UTF-8 st
1a4a0 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
1a4b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1a4c0 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
1a4d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1a4e0 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
1a4f0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
1a500 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
1a510 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
1a520 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a  .  In all cases.
1a530 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70  ** the name is p
1a540 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
1a550 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
1a560 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
1a570 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1a580 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74  must be one of t
1a590 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
1a5a0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
1a5b0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20  SQLITE_UTF16LE] 
1a5c0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
1a5d0 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  BE], indicating 
1a5e0 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75  that the user-su
1a5f0 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e  pplied.** routin
1a600 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20  e expects to be 
1a610 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20  passed pointers 
1a620 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64  to strings encod
1a630 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a  ed using UTF-8,.
1a640 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
1a650 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31  -endian or UTF-1
1a660 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73  6 big-endian res
1a670 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
1a680 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
1a690 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20  e user supplied 
1a6a0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
1a6b0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
1a6c0 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  fth.** argument.
1a6d0 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
1a6e0 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
1a6f0 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
1a700 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
1a710 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
1a720 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
1a730 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 20  ll it anymore). 
1a740 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 75 73  Each time the us
1a750 65 72 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 66  er.** supplied f
1a760 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
1a770 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64  ed, it is passed
1a780 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1a790 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a 2a  oid* passed as.*
1a7a0 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  * the fourth arg
1a7b0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1a7c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1a7d0 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  n() or.** sqlite
1a7e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1a7f0 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66 69  on16() as its fi
1a800 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
1a810 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  *.** The remaini
1a820 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ng arguments to 
1a830 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
1a840 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
1a850 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
1a860 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
1a870 79 20 61 20 5b 6c 65 6e 67 74 68 2c 20 64 61 74  y a [length, dat
1a880 61 5d 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a] pair and enco
1a890 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
1a8a0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
1a8b0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
1a8c0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
1a8d0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
1a8e0 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
1a8f0 72 65 67 69 73 74 65 72 65 64 2e 20 54 68 65 20  registered. The 
1a900 75 73 65 72 20 72 6f 75 74 69 6e 65 20 73 68 6f  user routine sho
1a910 75 6c 64 20 72 65 74 75 72 6e 20 6e 65 67 61 74  uld return negat
1a920 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73  ive, zero or pos
1a930 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68 65 20  itive if.** the 
1a940 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
1a950 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
1a960 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
1a970 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a  than the second.
1a980 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  ** string. i.e. 
1a990 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
1a9a0 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  G2)..**.** The s
1a9b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1a9c0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
1a9d0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1a9e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1a9f0 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68 61  ().** excapt tha
1aa00 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
1aa10 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
1aa20 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
1aa30 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
1aa40 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  llation.  The de
1aa50 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
1aa60 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
1aa70 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
1aa80 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
1aa90 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
1aaa0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1aab0 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
1aac0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
1aad0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1aae0 69 6f 6e 5f 76 32 28 29 2e 20 20 43 6f 6c 6c 61  ion_v2().  Colla
1aaf0 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f  tions are destro
1ab00 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79  yed when.** they
1ab10 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
1ab20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74  by later calls t
1ab30 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
1ab40 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
1ab50 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  ns.** or when th
1ab60 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74  e [sqlite3*] dat
1ab70 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73 20  abase handle is 
1ab80 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
1ab90 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
1aba0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1abb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1abc0 6f 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  on_v2() interfac
1abd0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
1abe0 6c 20 61 6e 64 0a 2a 2a 20 73 75 62 6a 65 63 74  l and.** subject
1abf0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1ac00 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20  ture releases.  
1ac10 54 68 65 20 6f 74 68 65 72 20 63 6f 6c 6c 61 74  The other collat
1ac20 69 6f 6e 20 63 72 65 61 74 69 6f 6e 0a 2a 2a 20  ion creation.** 
1ac30 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 73 74  functions are st
1ac40 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  able..*/.int sql
1ac50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
1ac60 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
1ac70 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
1ac80 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
1ac90 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
1aca0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
1acb0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
1acc0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
1acd0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
1ace0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
1acf0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
1ad00 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
1ad10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
1ad20 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
1ad30 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
1ad40 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
1ad50 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
1ad60 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
1ad70 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
1ad80 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
1ad90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
1ada0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
1adb0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
1adc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
1add0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
1ade0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
1adf0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
1ae00 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1ae10 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1ae20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
1ae30 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
1ae40 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
1ae50 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  backs.**.** To a
1ae60 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
1ae70 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
1ae80 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
1ae90 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
1aea0 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
1aeb0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
1aec0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
1aed0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
1aee0 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ith the.** datab
1aef0 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62 65  ase handle to be
1af00 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72   called whenever
1af10 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
1af20 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1af30 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e   is.** required.
1af40 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75  .**.** If the fu
1af50 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
1af60 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
1af70 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
1af80 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
1af90 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
1afa0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
1afb0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
1afc0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
1afd0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
1afe0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 49  oded in UTF-8. I
1aff0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
1b000 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
1b010 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65  s used, the name
1b020 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20  s.** are passed 
1b030 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
1b040 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
1b050 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74   order. A call t
1b060 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63  o either.** func
1b070 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e  tion replaces an
1b080 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62  y existing callb
1b090 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ack..**.** When 
1b0a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1b0b0 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
1b0c0 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
1b0d0 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
1b0e0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
1b0f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1b100 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
1b110 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
1b120 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1b130 64 65 64 31 36 28 29 2e 20 54 68 65 20 73 65 63  ded16(). The sec
1b140 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
1b150 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1b160 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 68 69 72  handle. The thir
1b170 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
1b180 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
1b190 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
1b1a0 36 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  6BE], or.** [SQL
1b1b0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
1b1c0 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
1b1d0 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
1b1e0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
1b1f0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
1b200 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
1b210 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
1b220 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
1b230 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
1b240 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
1b250 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  equence..**.** T
1b260 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1b270 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
1b280 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
1b290 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
1b2a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
1b2b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
1b2c0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
1b2d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
1b2e0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
1b2f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1b300 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
1b310 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
1b320 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
1b330 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
1b340 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
1b350 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
1b360 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
1b370 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
1b380 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1b390 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
1b3a0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
1b3b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
1b3c0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
1b3d0 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
1b3e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
1b3f0 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
1b400 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
1b410 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
1b420 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
1b430 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
1b440 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
1b450 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
1b460 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
1b470 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
1b480 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
1b490 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
1b4a0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
1b4b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
1b4c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1b4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b4e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
1b4f0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
1b500 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
1b510 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
1b520 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
1b530 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
1b540 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
1b550 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
1b560 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
1b570 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
1b580 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
1b590 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
1b5a0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
1b5b0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
1b5c0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1b5d0 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
1b5e0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
1b5f0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
1b600 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
1b610 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
1b620 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
1b630 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
1b640 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
1b650 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1b660 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
1b670 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
1b680 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
1b690 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
1b6a0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
1b6b0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
1b6c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b6d0 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65 63  F:  Suspend Exec
1b6e0 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
1b6f0 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69  t Time.**.** Thi
1b700 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
1b710 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
1b720 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
1b730 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 61 20 6e  execution.** a n
1b740 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
1b750 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
1b760 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
1b770 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
1b780 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1b790 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
1b7a0 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
1b7b0 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65  with .** millise
1b7c0 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
1b7d0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
1b7e0 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
1b7f0 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68  ded up to .** th
1b800 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
1b810 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
1b820 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1b830 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a  sleep actually .
1b840 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
1b850 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
1b860 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
1b870 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
1b880 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
1b890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b8a0 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
1b8b0 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
1b8c0 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
1b8d0 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  * If this global
1b8e0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
1b8f0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
1b900 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
1b910 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
1b920 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20 64   folder (a.ka. d
1b930 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
1b940 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
1b950 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
1b960 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  y SQLite will be
1b970 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
1b980 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74  directory.  If t
1b990 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
1b9a0 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  is NULL pointer,
1b9b0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f 65   then SQLite doe
1b9c0 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
1b9d0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 65  n appropriate te
1b9e0 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65 20  mporary.** file 
1b9f0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
1ba00 20 4f 6e 63 65 20 5b 73 71 6c 69 74 65 33 5f 6f   Once [sqlite3_o
1ba10 70 65 6e 28 29 5d 20 68 61 73 20 62 65 65 6e 20  pen()] has been 
1ba20 63 61 6c 6c 65 64 2c 20 63 68 61 6e 67 69 6e 67  called, changing
1ba30 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 77   this variable w
1ba40 69 6c 6c 0a 2a 2a 20 69 6e 76 61 6c 69 64 61 74  ill.** invalidat
1ba50 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 65  e the current te
1ba60 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61 73 65  mporary database
1ba70 2c 20 69 66 20 61 6e 79 2e 20 20 47 65 6e 65 72  , if any.  Gener
1ba80 61 6c 6c 79 20 73 70 65 61 6b 69 6e 67 2c 0a 2a  ally speaking,.*
1ba90 2a 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * it is not safe
1baa0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 69 73 20   to invoke this 
1bab0 72 6f 75 74 69 6e 65 20 61 66 74 65 72 20 5b 73  routine after [s
1bac0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 68  qlite3_open()] h
1bad0 61 73 0a 2a 2a 20 62 65 65 6e 20 63 61 6c 6c 65  as.** been calle
1bae0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  d..*/.SQLITE_EXT
1baf0 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
1bb00 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
1bb10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1bb20 46 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65 20  F:  Test To See 
1bb30 49 66 20 54 68 65 20 44 61 74 61 62 73 65 20 49  If The Databse I
1bb40 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74  s In Auto-Commit
1bb50 20 4d 6f 64 65 0a 2a 2a 0a 2a 2a 20 54 65 73 74   Mode.**.** Test
1bb60 20 74 6f 20 73 65 65 20 77 68 65 74 68 65 72 20   to see whether 
1bb70 6f 72 20 6e 6f 74 20 74 68 65 20 64 61 74 61 62  or not the datab
1bb80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1bb90 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a  s in autocommit.
1bba0 2a 2a 20 6d 6f 64 65 2e 20 20 52 65 74 75 72 6e  ** mode.  Return
1bbb0 20 54 52 55 45 20 69 66 20 69 74 20 69 73 20 61   TRUE if it is a
1bbc0 6e 64 20 46 41 4c 53 45 20 69 66 20 6e 6f 74 2e  nd FALSE if not.
1bbd0 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64    Autocommit mod
1bbe0 65 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65  e is on.** by de
1bbf0 66 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d  fault.  Autocomm
1bc00 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  it is disabled b
1bc10 79 20 61 20 42 45 47 49 4e 20 73 74 61 74 65 6d  y a BEGIN statem
1bc20 65 6e 74 20 61 6e 64 20 72 65 65 6e 61 62 6c 65  ent and reenable
1bc30 64 0a 2a 2a 20 62 79 20 74 68 65 20 6e 65 78 74  d.** by the next
1bc40 20 43 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c 42   COMMIT or ROLLB
1bc50 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ACK..**.** If an
1bc60 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
1bc70 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
1bc80 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
1bc90 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
1bca0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
1bcb0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
1bcc0 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
1bcd0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
1bce0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
1bcf0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
1bd00 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
1bd10 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1bd20 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54  API3REF:  Find T
1bd30 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
1bd40 6c 65 20 41 73 73 6f 63 69 61 74 65 64 20 57 69  le Associated Wi
1bd50 74 68 20 41 20 50 72 65 70 61 72 65 64 20 53 74  th A Prepared St
1bd60 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52 65  atement.**.** Re
1bd70 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
1bd80 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e  3*] database han
1bd90 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a  dle to which a.*
1bda0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
1bdb0 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
1bdc0 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a  ment] belongs..*
1bdd0 2a 20 54 68 69 73 20 69 73 20 74 68 65 20 73 61  * This is the sa
1bde0 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  me database hand
1bdf0 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74  le that was.** t
1be00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1be10 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
1be20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1be30 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a  or its variants.
1be40 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65 64  ** that was used
1be50 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 73   to create the s
1be60 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1be70 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a  first place..*/.
1be80 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
1be90 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
1bea0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a  e3_stmt*);.../*.
1beb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1bec0 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
1bed0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
1bee0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68  llbacks.**.** Th
1bef0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
1bf00 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
1bf10 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 62  k functions to b
1bf20 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
1bf30 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
1bf40 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  .** is committed
1bf50 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e   or rolled back.
1bf60 20 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d    The pArg argum
1bf70 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
1bf80 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20  rough.** to the 
1bf90 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68  callback.  If th
1bfa0 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
1bfb0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
1bfc0 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73  tion .** returns
1bfd0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1bfe0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
1bff0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
1c000 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ollback..**.** I
1c010 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
1c020 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
1c030 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
1c040 73 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20  s pArg value is 
1c050 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68  returned..** Oth
1c060 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72  erwise NULL is r
1c070 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  eturned..**.** R
1c080 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
1c090 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
1c0a0 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
1c0b0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ..**.** For the 
1c0c0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
1c0d0 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74   API, a transact
1c0e0 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68  ion is said to h
1c0f0 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c  ave been .** rol
1c100 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
1c110 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
1c120 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
1c130 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
1c140 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
1c150 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
1c160 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
1c170 63 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54 68 65  ck to occur. The
1c180 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73   .** callback is
1c190 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
1c1a0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
1c1b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
1c1c0 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62 65  olled.** back be
1c1d0 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
1c1e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1c1f0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
1c200 68 65 73 65 20 61 72 65 20 65 78 70 65 72 69 6d  hese are experim
1c210 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
1c220 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74   and are subject
1c230 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76   to change..*/.v
1c240 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
1c250 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
1c260 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
1c270 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
1c280 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
1c290 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
1c2a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
1c2b0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1c2c0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
1c2d0 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
1c2e0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
1c2f0 2a 2a 20 52 65 67 69 73 74 65 72 20 61 20 63 61  ** Register a ca
1c300 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1c310 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
1c320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65  e connection ide
1c330 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ntified by the .
1c340 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  ** first argumen
1c350 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  t to be invoked 
1c360 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
1c370 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
1c380 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
1c390 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
1c3a0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
1c3b0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
1c3c0 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  unction for the 
1c3d0 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73  same .** databas
1c3e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1c3f0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
1c400 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
1c410 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
1c420 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
1c430 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
1c440 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75  n a .** row is u
1c450 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
1c460 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 68 65   or deleted. The
1c470 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1c480 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1c490 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20  is.** a copy of 
1c4a0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1c4b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70  nt to sqlite3_up
1c4c0 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68 65  date_hook(). The
1c4d0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b   second callback
1c4e0 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73   .** argument is
1c4f0 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f 49   one of SQLITE_I
1c500 4e 53 45 52 54 2c 20 53 51 4c 49 54 45 5f 44 45  NSERT, SQLITE_DE
1c510 4c 45 54 45 20 6f 72 20 53 51 4c 49 54 45 5f 55  LETE or SQLITE_U
1c520 50 44 41 54 45 2c 20 64 65 70 65 6e 64 69 6e 67  PDATE, depending
1c530 0a 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  .** on the opera
1c540 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
1c550 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f   the callback to
1c560 20 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68 65   be invoked. The
1c570 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66   third and .** f
1c580 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
1c590 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1c5a0 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
1c5b0 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
1c5c0 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e   and .** table n
1c5d0 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
1c5e0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
1c5f0 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62   The final callb
1c600 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
1c610 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f   .** the rowid o
1c620 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68  f the row. In th
1c630 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64  e case of an upd
1c640 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65  ate, this is the
1c650 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a   rowid after .**
1c660 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
1c670 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  s place..**.** T
1c680 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
1c690 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
1c6a0 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
1c6b0 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a  em tables are.**
1c6c0 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20   modified (i.e. 
1c6d0 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
1c6e0 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
1c6f0 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  e)..**.** If ano
1c700 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
1c710 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
1c720 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72  istered, its pAr
1c730 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  g value is retur
1c740 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  ned..** Otherwis
1c750 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
1c760 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ed..*/.void *sql
1c770 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
1c780 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
1c790 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
1c7a0 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
1c7b0 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
1c7c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
1c7d0 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
1c7e0 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62   CAPI3REF:  Enab
1c7f0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68  le Or Disable Sh
1c800 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65  ared Pager Cache
1c810 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1c820 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
1c830 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
1c840 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
1c850 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
1c860 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
1c870 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
1c880 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74  connections to t
1c890 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1c8a0 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20  ..** Sharing is 
1c8b0 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
1c8c0 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20  rgument is true 
1c8d0 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20  and disabled if 
1c8e0 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  the argument.** 
1c8f0 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20  is false..**.** 
1c900 42 65 67 69 6e 6e 69 6e 67 20 69 6e 20 53 51 4c  Beginning in SQL
1c910 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1c920 30 2c 20 63 61 63 68 65 20 73 68 61 72 69 6e 67  0, cache sharing
1c930 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
1c940 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20  disabled.** for 
1c950 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
1c960 73 2e 20 20 49 6e 20 70 72 69 6f 72 20 76 65 72  s.  In prior ver
1c970 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
1c980 20 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20   sharing was.** 
1c990 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
1c9a0 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
1c9b0 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
1c9c0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20  **.** The cache 
1c9d0 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
1c9e0 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
1c9f0 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
1ca00 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
1ca10 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
1ca20 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1ca30 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
1ca40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1ca50 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
1ca60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ca70 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
1ca80 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
1ca90 6f 64 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  ode that was.** 
1caa0 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
1cab0 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
1cac0 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69  opened..**.** Vi
1cad0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e  rtual tables can
1cae0 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68  not be used with
1caf0 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e   a shared cache.
1cb00 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a    When shared.**
1cb10 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
1cb20 64 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  d, the sqlite3_c
1cb30 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 41  reate_module() A
1cb40 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  PI used to regis
1cb50 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  ter.** virtual t
1cb60 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79  ables will alway
1cb70 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  s return an erro
1cb80 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  r..**.** This ro
1cb90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
1cba0 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
1cbb0 72 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a  red cache was.**
1cbc0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
1cbd0 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  bled successfull
1cbe0 79 2e 20 20 41 6e 20 5b 53 51 4c 49 54 45 5f 45  y.  An [SQLITE_E
1cbf0 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64  RROR | error cod
1cc00 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  e].** is returne
1cc10 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  d otherwise..**.
1cc20 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20  ** Shared cache 
1cc30 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1cc40 65 66 61 75 6c 74 20 66 6f 72 20 62 61 63 6b 77  efault for backw
1cc50 61 72 64 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ard compatibilit
1cc60 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
1cc70 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
1cc80 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
1cc90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41 74  ** CAPI3REF:  At
1cca0 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
1ccb0 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20  ap Memory.**.** 
1ccc0 41 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  Attempt to free 
1ccd0 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20  N bytes of heap 
1cce0 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
1ccf0 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
1cd00 74 69 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tial.** memory a
1cd10 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20  llocations held 
1cd20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
1cd30 6c 69 62 72 61 72 79 20 28 65 78 61 6d 70 6c 65  library (example
1cd40 3a 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 75 73 65  : memory .** use
1cd50 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62  d to cache datab
1cd60 61 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d 70  ase pages to imp
1cd70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
1cd80 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  )..**.** This fu
1cd90 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 20  nction is not a 
1cda0 70 61 72 74 20 6f 66 20 73 74 61 6e 64 61 72 64  part of standard
1cdb0 20 62 75 69 6c 64 73 2e 20 20 49 74 20 69 73 20   builds.  It is 
1cdc0 6f 6e 6c 79 20 63 72 65 61 74 65 64 0a 2a 2a 20  only created.** 
1cdd0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
1cde0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  piled with the S
1cdf0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
1ce00 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 20 6d  ORY_MANAGEMENT m
1ce10 61 63 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  acro..*/.int sql
1ce20 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
1ce30 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
1ce40 20 43 41 50 49 33 52 45 46 3a 20 20 49 6d 70 6f   CAPI3REF:  Impo
1ce50 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65  se A Limit On He
1ce60 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 50 6c  ap Size.**.** Pl
1ce70 61 63 65 20 61 20 22 73 6f 66 74 22 20 6c 69 6d  ace a "soft" lim
1ce80 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  it on the amount
1ce90 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
1cea0 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
1ceb0 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c 69  cated.** by SQLi
1cec0 74 65 2e 20 20 49 66 20 61 6e 20 69 6e 74 65 72  te.  If an inter
1ced0 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  nal allocation i
1cee0 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20  s requested .** 
1cef0 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65  that would excee
1cf00 64 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  d the specified 
1cf10 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f  limit, [sqlite3_
1cf20 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
1cf30 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  ] is.** invoked 
1cf40 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
1cf50 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d  s to free up som
1cf60 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74  e space before t
1cf70 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  he allocation.**
1cf80 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20   is made..**.** 
1cf90 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c  The limit is cal
1cfa0 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61  led "soft", beca
1cfb0 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  use if [sqlite3_
1cfc0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
1cfd0 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65  ] cannot.** free
1cfe0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
1cff0 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ry to prevent th
1d000 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69  e limit from bei
1d010 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20  ng exceeded,.** 
1d020 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c  the memory is al
1d030 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61  located anyway a
1d040 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f  nd the current o
1d050 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1d060 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74  s..**.** A negat
1d070 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75  ive or zero valu
1d080 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68  e for N means th
1d090 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73  at there is no s
1d0a0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61  oft heap limit a
1d0b0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  nd.** [sqlite3_r
1d0c0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
1d0d0 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61   will only be ca
1d0e0 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
1d0f0 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
1d100 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  * The default va
1d110 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74  lue for the soft
1d120 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a   heap limit is z
1d130 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ero..**.** SQLit
1d140 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65  e makes a best e
1d150 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74  ffort to honor t
1d160 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
1d170 69 74 2e 20 20 42 75 74 20 69 66 20 69 74 0a 2a  it.  But if it.*
1d180 2a 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 72  * is unable to r
1d190 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73 61  educe memory usa
1d1a0 67 65 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66  ge below the sof
1d1b0 74 20 6c 69 6d 69 74 2c 20 65 78 65 63 75 74 69  t limit, executi
1d1c0 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69  on will.** conti
1d1d0 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f  nue without erro
1d1e0 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f  r or notificatio
1d1f0 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 20  n.  This is why 
1d200 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a  the limit is .**
1d210 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22   called a "soft"
1d220 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61   limit.  It is a
1d230 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a  dvisory only..**
1d240 0a 2a 2a 20 54 68 65 20 73 6f 66 74 20 68 65 61  .** The soft hea
1d250 70 20 6c 69 6d 69 74 20 69 73 20 69 6d 70 6c 65  p limit is imple
1d260 6d 65 6e 74 65 64 20 75 73 69 6e 67 20 74 68 65  mented using the
1d270 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d280 5f 61 6c 61 72 6d 28 29 5d 0a 2a 2a 20 69 6e 74  _alarm()].** int
1d290 65 72 66 61 63 65 2e 20 20 4f 6e 6c 79 20 61 20  erface.  Only a 
1d2a0 73 69 6e 67 6c 65 20 6d 65 6d 6f 72 79 20 61 6c  single memory al
1d2b0 61 72 6d 20 69 73 20 61 76 61 69 6c 61 62 6c 65  arm is available
1d2c0 20 69 6e 20 74 68 65 20 64 65 66 61 75 6c 74 0a   in the default.
1d2d0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
1d2e0 6e 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  n.  This means t
1d2f0 68 61 74 20 69 66 20 74 68 65 20 61 70 70 6c 69  hat if the appli
1d300 63 61 74 69 6f 6e 20 61 6c 73 6f 20 75 73 65 73  cation also uses
1d310 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61   the.** memory a
1d320 6c 61 72 6d 20 69 6e 74 65 72 66 61 63 65 20 69  larm interface i
1d330 74 20 77 69 6c 6c 20 69 6e 74 65 72 66 65 72 65  t will interfere
1d340 20 77 69 74 68 20 74 68 65 20 6f 70 65 72 61 74   with the operat
1d350 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 73 6f  ion of the.** so
1d360 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e  ft heap limit an
1d370 64 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  d undefined beha
1d380 76 69 6f 72 20 77 69 6c 6c 20 72 65 73 75 6c 74  vior will result
1d390 2e 20 20 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  .  .**.** Prior 
1d3a0 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
1d3b0 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f  n 3.5.0, this ro
1d3c0 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74  utine only const
1d3d0 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72  rained the memor
1d3e0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62  y.** allocated b
1d3f0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
1d400 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72  d - the same thr
1d410 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69  ead in which thi
1d420 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e  s routine.** run
1d430 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69  s.  Beginning wi
1d440 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  th SQLite versio
1d450 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66  n 3.5.0, the sof
1d460 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a  t heap limit is.
1d470 2a 2a 20 61 70 70 6c 69 65 64 20 63 75 6d 75 6c  ** applied cumul
1d480 61 74 69 76 65 6c 79 20 74 6f 20 61 6c 6c 20 74  atively to all t
1d490 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20  hreads..*/.void 
1d4a0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
1d4b0 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f  p_limit(int);../
1d4c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1d4d0 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61  Extract Metadata
1d4e0 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20   About A Column 
1d4f0 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  Of A Table.**.**
1d500 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   This routine.**
1d510 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61   returns meta-da
1d520 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
1d530 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
1d540 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61 73  specific databas
1d550 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73  e.** table acces
1d560 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
1d570 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  connection handl
1d580 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
1d590 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a  first function .
1d5a0 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ** argument..**.
1d5b0 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  ** The column is
1d5c0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
1d5d0 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
1d5e0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
1d5f0 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68  meters to .** th
1d600 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  is function. The
1d610 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1d620 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
1d630 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1d640 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
1d650 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20  ain", "temp" or 
1d660 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
1d670 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
1d680 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
1d690 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
1d6a0 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
1d6b0 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
1d6c0 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
1d6d0 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
1d6e0 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
1d6f0 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
1d700 68 6d 20 61 73 20 74 68 65 20 64 61 74 61 62 61  hm as the databa
1d710 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74  se engine uses t
1d720 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  o .** resolve un
1d730 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
1d740 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
1d750 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20  * The third and 
1d760 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1d770 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
1d780 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
1d790 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20   and column .** 
1d7a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
1d7b0 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
1d7c0 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
1d7d0 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
1d7e0 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65  eters .** may be
1d7f0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74   NULL..**.** Met
1d800 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  a information is
1d810 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69   returned by wri
1d820 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f  ting to the memo
1d830 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73  ry locations pas
1d840 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74  sed as.** the 5t
1d850 68 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  h and subsequent
1d860 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1d870 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e  his function. An
1d880 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61  y of these .** a
1d890 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20  rguments may be 
1d8a0 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63  NULL, in which c
1d8b0 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ase the correspo
1d8c0 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66  nding element of
1d8d0 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d   meta .** inform
1d8e0 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65  ation is ommitte
1d8f0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  d..**.** <pre>.*
1d900 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20 20 20  * Parameter     
1d910 4f 75 74 70 75 74 20 54 79 70 65 20 20 20 20 20  Output Type     
1d920 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20   Description.** 
1d930 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1d940 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1d950 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20  ---.**.**   5th 
1d960 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68          const ch
1d970 61 72 2a 20 20 20 20 20 20 44 61 74 61 20 74 79  ar*      Data ty
1d980 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20  pe.**   6th     
1d990 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20      const char* 
1d9a0 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65       Name of the
1d9b0 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69   default collati
1d9c0 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20  on sequence .** 
1d9d0 20 20 37 74 68 20 20 20 20 20 20 20 20 20 69 6e    7th         in
1d9e0 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54  t              T
1d9f0 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d  rue if the colum
1da00 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
1da10 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20   constraint.**  
1da20 20 38 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   8th         int
1da30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
1da40 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
1da50 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
1da60 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20  PRIMARY KEY.**  
1da70 20 39 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   9th         int
1da80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
1da90 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
1daa0 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e   is AUTOINCREMEN
1dab0 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a  T.** </pre>.**.*
1dac0 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20  *.** The memory 
1dad0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
1dae0 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e  e character poin
1daf0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f  ters returned fo
1db00 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72  r the .** declar
1db10 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63  ation type and c
1db20 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
1db30 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20  e is valid only 
1db40 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a  until the next .
1db50 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73  ** call to any s
1db60 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69  qlite API functi
1db70 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
1db80 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65   specified table
1db90 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76   is actually a v
1dba0 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72  iew, then an err
1dbb0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  or is returned..
1dbc0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65  **.** If the spe
1dbd0 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73  cified column is
1dbe0 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20   "rowid", "oid" 
1dbf0 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64  or "_rowid_" and
1dc00 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20   an .** INTEGER 
1dc10 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75  PRIMARY KEY colu
1dc20 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c  mn has been expl
1dc30 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c  icitly declared,
1dc40 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
1dc50 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20   .** parameters 
1dc60 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20  are set for the 
1dc70 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
1dc80 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74  red column. If t
1dc90 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78  here is no.** ex
1dca0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
1dcb0 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68  d IPK column, th
1dcc0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70 61  en the output pa
1dcd0 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
1dce0 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a   as .** follows:
1dcf0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
1dd00 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
1dd10 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
1dd20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1dd30 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
1dd40 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
1dd50 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
1dd60 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
1dd70 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
1dd80 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54  * </pre>.**.** T
1dd90 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
1dda0 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72   load one or mor
1ddb0 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64  e schemas from d
1ddc0 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49  atabase files. I
1ddd0 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63  f an.** error oc
1dde0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73  curs during this
1ddf0 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
1de00 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61  the requested ta
1de10 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  ble or column.**
1de20 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64   cannot be found
1de30 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f  , an SQLITE erro
1de40 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
1de50 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  ed and an error 
1de60 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20  message.** left 
1de70 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
1de80 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65  handle (to be re
1de90 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
1dea0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
1deb0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
1dec0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
1ded0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
1dee0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1def0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
1df00 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
1df10 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65  ETADATA preproce
1df20 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
1df30 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
1df40 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
1df50 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c  _metadata(.  sql
1df60 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1df70 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e           /* Conn
1df80 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f  ection handle */
1df90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1dfa0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f  DbName,        /
1dfb0 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20  * Database name 
1dfc0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e  or NULL */.  con
1dfd0 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e  st char *zTableN
1dfe0 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c  ame,     /* Tabl
1dff0 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73  e name */.  cons
1e000 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e  t char *zColumnN
1e010 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d  ame,    /* Colum
1e020 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72  n name */.  char
1e030 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54   const **pzDataT
1e040 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55  ype,    /* OUTPU
1e050 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61  T: Declared data
1e060 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20   type */.  char 
1e070 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65  const **pzCollSe
1e080 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  q,     /* OUTPUT
1e090 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  : Collation sequ
1e0a0 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69  ence name */.  i
1e0b0 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20  nt *pNotNull,   
1e0c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
1e0d0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f  TPUT: True if NO
1e0e0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
1e0f0 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e  t exists */.  in
1e100 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20  t *pPrimaryKey, 
1e110 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1e120 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
1e130 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a  umn part of PK *
1e140 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e  /.  int *pAutoin
1e150 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c               
1e160 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
1e170 69 66 20 63 6f 6c 75 6d 73 20 69 73 20 61 75 74  if colums is aut
1e180 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29  o-increment */.)
1e190 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e1a0 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  F: Load An Exten
1e1b0 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d  sion.**.** Attem
1e1c0 70 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53 51  pt to load an SQ
1e1d0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
1e1e0 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
1e1f0 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   in the file.** 
1e200 7a 46 69 6c 65 2e 20 20 54 68 65 20 65 6e 74 72  zFile.  The entr
1e210 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63  y point is zProc
1e220 2e 20 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20  .  zProc may be 
1e230 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
1e240 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  the.** name of t
1e250 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 64  he entry point d
1e260 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69  efaults to "sqli
1e270 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e  te3_extension_in
1e280 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  it"..**.** Retur
1e290 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
1e2a0 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
1e2b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
1e2c0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
1e2d0 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ong..**.** If an
1e2e0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e   error occurs an
1e2f0 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f  d pzErrMsg is no
1e300 74 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c 20 2a  t 0, then fill *
1e310 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a  pzErrMsg with .*
1e320 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * error message 
1e330 74 65 78 74 2e 20 20 54 68 65 20 63 61 6c 6c 69  text.  The calli
1e340 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ng function shou
1e350 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d  ld free this mem
1e360 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69 6e  ory.** by callin
1e370 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  g [sqlite3_free(
1e380 29 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73  )]..**.** Extens
1e390 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74  ion loading must
1e3a0 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   be enabled usin
1e3b0 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
1e3c0 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
1e3d0 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ()].** prior to 
1e3e0 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49  calling this API
1e3f0 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c   or an error wil
1e400 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a  l be returned..*
1e410 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f  /.int sqlite3_lo
1e420 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20  ad_extension(.  
1e430 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1e440 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68        /* Load th
1e450 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f  e extension into
1e460 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
1e470 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63  onnection */.  c
1e480 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
1e490 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20  ,    /* Name of 
1e4a0 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61  the shared libra
1e4b0 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78  ry containing ex
1e4c0 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  tension */.  con
1e4d0 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20  st char *zProc, 
1e4e0 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e     /* Entry poin
1e4f0 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d  t.  Derived from
1e500 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20   zFile if 0 */. 
1e510 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67   char **pzErrMsg
1e520 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72         /* Put er
1e530 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65  ror message here
1e540 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a   if not 0 */.);.
1e550 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e560 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61    Enable Or Disa
1e570 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  ble Extension Lo
1e580 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f 20 61  ading.**.** So a
1e590 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
1e5a0 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
1e5b0 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
1e5c0 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
1e5d0 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
1e5e0 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
1e5f0 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
1e600 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
1e610 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
1e620 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
1e630 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
1e640 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
1e650 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41  e following.** A
1e660 50 49 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  PI is provided t
1e670 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
1e680 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
1e690 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
1e6a0 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20  on and.** off.  
1e6b0 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  It is off by def
1e6c0 61 75 6c 74 2e 20 20 53 65 65 20 74 69 63 6b 65  ault.  See ticke
1e6d0 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 43  t #1863..**.** C
1e6e0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
1e6f0 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74   with onoff==1 t
1e700 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
1e710 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61   loading on.** a
1e720 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
1e730 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
1e740 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
1e750 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  in..*/.int sqlit
1e760 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
1e770 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33  xtension(sqlite3
1e780 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29   *db, int onoff)
1e790 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e7a0 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d  F: Make Arrangem
1e7b0 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69  ents To Automati
1e7c0 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78  cally Load An Ex
1e7d0 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 52 65  tension.**.** Re
1e7e0 67 69 73 74 65 72 20 61 6e 20 65 78 74 65 6e 73  gister an extens
1e7f0 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  ion entry point 
1e800 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74 69  that is automati
1e810 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a  cally invoked.**
1e820 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20   whenever a new 
1e830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e840 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75 73  ion is opened us
1e850 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1e860 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1e870 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20  3_open16()], or 
1e880 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1e890 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ()]..**.** This 
1e8a0 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b  API can be invok
1e8b0 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74  ed at program st
1e8c0 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74  artup in order t
1e8d0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e  o register.** on
1e8e0 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63  e or more static
1e8f0 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65  ally linked exte
1e900 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c  nsions that will
1e910 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a   be available.**
1e920 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61   to all new data
1e930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1e940 2e 0a 2a 2a 0a 2a 2a 20 44 75 70 6c 69 63 61 74  ..**.** Duplicat
1e950 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65  e extensions are
1e960 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c   detected so cal
1e970 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
1e980 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  e multiple.** ti
1e990 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
1e9a0 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68  e extension is h
1e9b0 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 54  armless..**.** T
1e9c0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1e9d0 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
1e9e0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
1e9f0 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74 68 61   an array.** tha
1ea00 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72  t is obtained fr
1ea10 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2e 20 20 49 66  om malloc().  If
1ea20 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72   you run a memor
1ea30 79 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65  y leak.** checke
1ea40 72 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61  r on your progra
1ea50 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73  m and it reports
1ea60 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20   a leak because 
1ea70 6f 66 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79  of this.** array
1ea80 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73  , then invoke [s
1ea90 71 6c 69 74 65 33 5f 61 75 74 6f 6d 61 74 69 63  qlite3_automatic
1eaa0 5f 65 78 74 65 6e 73 69 6f 6e 5f 72 65 73 65 74  _extension_reset
1eab0 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20  ()] prior.** to 
1eac0 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65  shutdown to free
1ead0 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a   the memory..**.
1eae0 2a 2a 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74  ** Automatic ext
1eaf0 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63  ensions apply ac
1eb00 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73  ross all threads
1eb10 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1eb20 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69  erface is experi
1eb30 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
1eb40 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
1eb50 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e  or.** removal in
1eb60 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
1eb70 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
1eb80 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  nt sqlite3_auto_
1eb90 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a  extension(void *
1eba0 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a  xEntryPoint);...
1ebb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ebc0 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20  Reset Automatic 
1ebd0 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
1ebe0 67 0a 2a 2a 0a 2a 2a 20 44 69 73 61 62 6c 65 20  g.**.** Disable 
1ebf0 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72  all previously r
1ec00 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61  egistered automa
1ec10 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20  tic extensions. 
1ec20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   This.** routine
1ec30 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
1ec40 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 20  ct of all prior 
1ec50 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d 61 74  [sqlite3_automat
1ec60 69 63 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a  ic_extension()].
1ec70 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20  ** calls..**.** 
1ec80 54 68 69 73 20 63 61 6c 6c 20 64 69 73 61 62 6c  This call disabl
1ec90 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74  ed automatic ext
1eca0 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74  ensions in all t
1ecb0 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  hreads..**.** Th
1ecc0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1ecd0 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1ece0 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63   is subject to c
1ecf0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f  hange or.** remo
1ed00 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65  val in future re
1ed10 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
1ed20 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1ed30 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74  3_reset_auto_ext
1ed40 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a  ension(void);...
1ed50 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49  /*.****** EXPERI
1ed60 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74  MENTAL - subject
1ed70 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f   to change witho
1ed80 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a  ut notice ******
1ed90 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54  ********.**.** T
1eda0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
1edb0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
1edc0 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63  e mechanism is c
1edd0 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
1ede0 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
1edf0 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
1ee00 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
1ee10 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
1ee20 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
1ee30 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
1ee40 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
1ee50 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
1ee60 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
1ee70 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
1ee80 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
1ee90 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
1eea0 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
1eeb0 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
1eec0 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
1eed0 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
1eee0 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
1eef0 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
1ef00 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63  .*/../*.** Struc
1ef10 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68  tures used by th
1ef20 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
1ef30 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70  interface.*/.typ
1ef40 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
1ef50 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33  te3_vtab sqlite3
1ef60 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73  _vtab;.typedef s
1ef70 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
1ef80 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33  dex_info sqlite3
1ef90 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70  _index_info;.typ
1efa0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
1efb0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
1efc0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
1efd0 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72  sor;.typedef str
1efe0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
1eff0 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  le sqlite3_modul
1f000 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 6d 6f 64 75  e;../*.** A modu
1f010 6c 65 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66  le is a class of
1f020 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e   virtual tables.
1f030 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73    Each module is
1f040 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61   defined.** by a
1f050 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
1f060 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  e following stru
1f070 63 74 75 72 65 2e 20 20 54 68 69 73 20 73 74 72  cture.  This str
1f080 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a  ucture consists.
1f090 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74  ** mostly of met
1f0a0 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
1f0b0 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ule..*/.struct s
1f0c0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a  qlite3_module {.
1f0d0 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
1f0e0 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29    int (*xCreate)
1f0f0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
1f100 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
1f110 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
1f120 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
1f130 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
1f140 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
1f150 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
1f160 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
1f170 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  Connect)(sqlite3
1f180 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
1f190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
1f1a0 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
1f1b0 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
1f1c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
1f1d0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
1f1e0 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
1f1f0 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65   int (*xBestInde
1f200 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  x)(sqlite3_vtab 
1f210 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
1f220 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20  index_info*);.  
1f230 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63  int (*xDisconnec
1f240 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
1f250 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
1f260 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74  *xDestroy)(sqlit
1f270 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
1f280 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
1f290 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
1f2a0 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61  Tab, sqlite3_vta
1f2b0 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72  b_cursor **ppCur
1f2c0 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sor);.  int (*xC
1f2d0 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74  lose)(sqlite3_vt
1f2e0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
1f2f0 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71  nt (*xFilter)(sq
1f300 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
1f310 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20  r*, int idxNum, 
1f320 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53  const char *idxS
1f330 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  tr,.            
1f340 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71      int argc, sq
1f350 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72  lite3_value **ar
1f360 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65  gv);.  int (*xNe
1f370 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  xt)(sqlite3_vtab
1f380 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
1f390 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33   (*xEof)(sqlite3
1f3a0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
1f3b0 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29    int (*xColumn)
1f3c0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
1f3d0 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63  rsor*, sqlite3_c
1f3e0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20  ontext*, int);. 
1f3f0 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73   int (*xRowid)(s
1f400 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
1f410 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  or*, sqlite3_int
1f420 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69  64 *pRowid);.  i
1f430 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71  nt (*xUpdate)(sq
1f440 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e  lite3_vtab *, in
1f450 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  t, sqlite3_value
1f460 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74   **, sqlite3_int
1f470 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  64 *);.  int (*x
1f480 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76  Begin)(sqlite3_v
1f490 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
1f4a0 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
1f4b0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
1f4c0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69  ;.  int (*xCommi
1f4d0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
1f4e0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
1f4f0 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69  *xRollback)(sqli
1f500 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
1f510 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46  ;.  int (*xFindF
1f520 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33  unction)(sqlite3
1f530 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e  _vtab *pVtab, in
1f540 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68  t nArg, const ch
1f550 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20  ar *zName,.     
1f560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f570 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63    void (**pxFunc
1f580 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
1f590 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
1f5a0 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20  alue**),.       
1f5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f5c0 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 0a  void **ppArg);..
1f5d0 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29    int (*xRename)
1f5e0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
1f5f0 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72  Vtab, const char
1f600 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a   *zNew);.};../*.
1f610 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
1f620 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74  ndex_info struct
1f630 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73  ure and its subs
1f640 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65  tructures is use
1f650 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66  d to.** pass inf
1f660 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e  ormation into an
1f670 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65  d receive the re
1f680 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42 65  ply from the xBe
1f690 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68 6f  stIndex.** metho
1f6a0 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 5f  d of an sqlite3_
1f6b0 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69 65  module.  The fie
1f6c0 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75  lds under **Inpu
1f6d0 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20  ts** are the.** 
1f6e0 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49  inputs to xBestI
1f6f0 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61  ndex and are rea
1f700 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e  d-only.  xBestIn
1f710 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a  dex inserts its.
1f720 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1f730 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20  the **Outputs** 
1f740 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  fields..**.** Th
1f750 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
1f760 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48  array records WH
1f770 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
1f780 72 61 69 6e 74 73 20 6f 66 20 74 68 65 0a 2a 2a  raints of the.**
1f790 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20   form:.**.**    
1f7a0 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20 65       column OP e
1f7b0 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65 20  xpr.**.** Where 
1f7c0 4f 50 20 69 73 20 3d 2c 20 3c 2c 20 3c 3d 2c 20  OP is =, <, <=, 
1f7d0 3e 2c 20 6f 72 20 3e 3d 2e 20 20 54 68 65 20 70  >, or >=.  The p
1f7e0 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74  articular operat
1f7f0 6f 72 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  or is stored.** 
1f800 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  in aConstraint[]
1f810 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78 20  .op.  The index 
1f820 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
1f830 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a 20 61   stored in .** a
1f840 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f  Constraint[].iCo
1f850 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61 69  lumn.  aConstrai
1f860 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54  nt[].usable is T
1f870 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78  RUE if the.** ex
1f880 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d  pr on the right-
1f890 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65  hand side can be
1f8a0 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20   evaluated (and 
1f8b0 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61  thus the constra
1f8c0 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65  int.** is usable
1f8d0 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69  ) and false if i
1f8e0 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20  t cannot..**.** 
1f8f0 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75  The optimizer au
1f900 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65  tomatically inve
1f910 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65  rts terms of the
1f920 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63   form "expr OP c
1f930 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61  olumn".** and ma
1f940 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69  kes other simpli
1f950 66 69 63 61 74 69 6e 6f 73 20 74 6f 20 74 68 65  ficatinos to the
1f960 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e   WHERE clause in
1f970 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a   an attempt to.*
1f980 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48  * get as many WH
1f990 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73  ERE clause terms
1f9a0 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73   into the form s
1f9b0 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f  hown above as po
1f9c0 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 61  ssible..** The a
1f9d0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
1f9e0 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ay only reports 
1f9f0 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
1fa00 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65 63  ms in the correc
1fa10 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20 72  t.** form that r
1fa20 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 72 74  efer to the part
1fa30 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74  icular virtual t
1fa40 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69  able being queri
1fa50 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d  ed..**.** Inform
1fa60 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
1fa70 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
1fa80 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72  is stored in aOr
1fa90 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68  derBy[]..** Each
1faa0 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42   term of aOrderB
1fab0 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75  y records a colu
1fac0 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20  mn of the ORDER 
1fad0 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a  BY clause..**.**
1fae0 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   The xBestIndex 
1faf0 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c  method must fill
1fb00 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
1fb10 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61  e[] with informa
1fb20 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68  tion.** about wh
1fb30 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  at parameters to
1fb40 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72   pass to xFilter
1fb50 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65 78 3e  .  If argvIndex>
1fb60 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69  0 then.** the ri
1fb70 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  ght-hand side of
1fb80 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
1fb90 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ng aConstraint[]
1fba0 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a   is evaluated.**
1fbb0 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65   and becomes the
1fbc0 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e   argvIndex-th en
1fbd0 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49 66  try in argv.  If
1fbe0 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
1fbf0 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74  e[].omit.** is t
1fc00 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f  rue, then the co
1fc10 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75  nstraint is assu
1fc20 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20  med to be fully 
1fc30 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a  handled by the.*
1fc40 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * virtual table 
1fc50 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b  and is not check
1fc60 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69  ed again by SQLi
1fc70 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64  te..**.** The id
1fc80 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20  xNum and idxPtr 
1fc90 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72  values are recor
1fca0 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69  ded and passed i
1fcb0 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a 20  nto xFilter..** 
1fcc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1fcd0 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69  s used to free i
1fce0 64 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f 46  dxPtr if needToF
1fcf0 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75  reeIdxPtr is tru
1fd00 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64  e..**.** The ord
1fd10 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61  erByConsumed mea
1fd20 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66  ns that output f
1fd30 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c 6c  rom xFilter will
1fd40 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65   occur in.** the
1fd50 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74   correct order t
1fd60 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52  o satisfy the OR
1fd70 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f  DER BY clause so
1fd80 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74   that no separat
1fd90 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65  e.** sorting ste
1fda0 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  p is required..*
1fdb0 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74  *.** The estimat
1fdc0 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20  edCost value is 
1fdd0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74  an estimate of t
1fde0 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67  he cost of doing
1fdf0 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c   the.** particul
1fe00 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75  ar lookup.  A fu
1fe10 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62  ll scan of a tab
1fe20 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65  le with N entrie
1fe30 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  s should have.**
1fe40 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41   a cost of N.  A
1fe50 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f   binary search o
1fe60 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65  f a table of N e
1fe70 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
1fe80 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20  ve a.** cost of 
1fe90 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f  approximately lo
1fea0 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  g(N)..*/.struct 
1feb0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
1fec0 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73  fo {.  /* Inputs
1fed0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74 20   */.  const int 
1fee0 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  nConstraint;    
1fef0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e   /* Number of en
1ff00 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72  tries in aConstr
1ff10 61 69 6e 74 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  aint */.  const 
1ff20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
1ff30 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20  ndex_constraint 
1ff40 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
1ff50 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
1ff60 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65   /* Column on le
1ff70 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
1ff80 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
1ff90 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
1ffa0 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20   op;         /* 
1ffb0 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61  Constraint opera
1ffc0 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  tor */.     unsi
1ffd0 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65  gned char usable
1ffe0 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66  ;     /* True if
1fff0 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
20000 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20   is usable */.  
20010 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73     int iTermOffs
20020 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  et;          /* 
20030 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  Used internally 
20040 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f  - xBestIndex sho
20050 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20  uld ignore */.  
20060 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e 73 74 72  } *const aConstr
20070 61 69 6e 74 3b 20 20 20 20 20 20 2f 2a 20 54 61  aint;      /* Ta
20080 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61  ble of WHERE cla
20090 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
200a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e  */.  const int n
200b0 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
200c0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72  /* Number of ter
200d0 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20  ms in the ORDER 
200e0 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 63  BY clause */.  c
200f0 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
20100 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62  te3_index_orderb
20110 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  y {.     int iCo
20120 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
20130 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d     /* Column num
20140 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  ber */.     unsi
20150 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20  gned char desc; 
20160 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f        /* True fo
20170 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66  r DESC.  False f
20180 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a  or ASC. */.  } *
20190 63 6f 6e 73 74 20 61 4f 72 64 65 72 42 79 3b 20  const aOrderBy; 
201a0 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f          /* The O
201b0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
201c0 2f 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20  /..  /* Outputs 
201d0 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
201e0 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72  te3_index_constr
201f0 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20  aint_usage {.   
20200 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20   int argvIndex; 
20210 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20            /* if 
20220 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  >0, constraint i
20230 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74  s part of argv t
20240 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20  o xFilter */.   
20250 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
20260 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20  mit;      /* Do 
20270 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20  not code a test 
20280 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61  for this constra
20290 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73  int */.  } *cons
202a0 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  t aConstraintUsa
202b0 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
202c0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
202d0 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
202e0 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
202f0 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
20300 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
20310 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
20320 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
20330 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
20340 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
20350 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
20360 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
20370 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
20380 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
20390 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
203a0 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
203b0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
203c0 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
203d0 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
203e0 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
203f0 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
20400 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
20410 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
20420 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .};.#define SQLI
20430 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
20440 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66  INT_EQ    2.#def
20450 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
20460 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
20470 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
20480 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
20490 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66  INT_LE    8.#def
204a0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
204b0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20  _CONSTRAINT_LT  
204c0 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
204d0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
204e0 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64  AINT_GE    32.#d
204f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
20500 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41  EX_CONSTRAINT_MA
20510 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 54 68  TCH 64../*.** Th
20520 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
20530 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ed to register a
20540 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65   new module name
20550 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65 0a   with an SQLite.
20560 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
20570 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73  Module names mus
20580 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
20590 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67 20  before creating 
205a0 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  new.** virtual t
205b0 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64  ables on the mod
205c0 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75  ule, or before u
205d0 73 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e 67  sing preexisting
205e0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
205f0 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  es of the module
20600 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
20610 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a  _create_module(.
20620 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
20630 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
20640 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
20650 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
20660 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
20670 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
20680 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
20690 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
206a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
206b0 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20  e3_module *,    
206c0 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
206d0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
206e0 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 20 20  oid *           
206f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69            /* Cli
20700 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
20710 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
20720 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20  .);../*.** This 
20730 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e 74  routine is ident
20740 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71 6c 69  ical to the sqli
20750 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
20760 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f 76 65  e() method above
20770 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ,.** except that
20780 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65 73   it allows a des
20790 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
207a0 20 74 6f 20 62 65 20 73 70 65 63 69 66 69 65 64   to be specified
207b0 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e 20  . It is.** even 
207c0 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61  more experimenta
207d0 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73 74 20  l than the rest 
207e0 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
207f0 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e  ables API..*/.in
20800 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
20810 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71  _module_v2(.  sq
20820 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
20830 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
20840 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
20850 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
20860 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
20870 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
20880 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
20890 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
208a0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
208b0 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d  odule *,    /* M
208c0 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
208d0 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
208e0 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
208f0 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
20900 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
20910 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76  /xConnect */.  v
20920 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
20930 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64  oid*)     /* Mod
20940 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  ule destructor f
20950 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f  unction */.);../
20960 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c  *.** Every modul
20970 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
20980 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73   uses a subclass
20990 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
209a0 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74  g structure.** t
209b0 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72  o describe a par
209c0 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
209d0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
209e0 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77   Each subclass w
209f0 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 79 6c 6f 72  ill.** be taylor
20a00 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  ed to the specif
20a10 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20  ic needs of the 
20a20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
20a30 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a 2a 20  ation.   The.** 
20a40 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20  purpose of this 
20a50 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f  superclass is to
20a60 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20   define certain 
20a70 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 20  fields that are 
20a80 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c  common.** to all
20a90 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
20aa0 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56  tations..**.** V
20ab0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65  irtual tables me
20ac0 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e  thods can set an
20ad0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62   error message b
20ae0 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a  y assigning a.**
20af0 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
20b00 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70   from sqlite3_mp
20b10 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72 72 4d  rintf() to zErrM
20b20 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20  sg.  The method 
20b30 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63  should.** take c
20b40 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69  are that any pri
20b50 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65  or string is fre
20b60 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
20b70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 0a 2a  sqlite3_free().*
20b80 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67  * prior to assig
20b90 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e  ning a new strin
20ba0 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41  g to zErrMsg.  A
20bb0 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
20bc0 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c  essage.** is del
20bd0 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65  ivered up to the
20be0 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74   client applicat
20bf0 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20  ion, the string 
20c00 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
20c10 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62  cally.** freed b
20c20 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  y sqlite3_free()
20c30 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67   and the zErrMsg
20c40 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a   field will be z
20c50 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20  eroed.  Note.** 
20c60 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d 70 72  that sqlite3_mpr
20c70 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
20c80 65 33 5f 66 72 65 65 28 29 20 61 72 65 20 75 73  e3_free() are us
20c90 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 4d 73  ed on the zErrMs
20ca0 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e 63 65  g field.** since
20cb0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
20cc0 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70  are commonly imp
20cd0 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f 61 64  lemented in load
20ce0 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  able extensions 
20cf0 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20  which.** do not 
20d00 68 61 76 65 20 61 63 63 65 73 73 20 74 6f 20 73  have access to s
20d10 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 29 20  qlite3MPrintf() 
20d20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65 28 29  or sqlite3Free()
20d30 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
20d40 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e  te3_vtab {.  con
20d50 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
20d60 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20  e *pModule;  /* 
20d70 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74  The module for t
20d80 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c  his virtual tabl
20d90 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b  e */.  int nRef;
20da0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20db0 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
20dc0 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63  nternally */.  c
20dd0 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20  har *zErrMsg;   
20de0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
20df0 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * Error message 
20e00 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
20e10 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56  intf() */.  /* V
20e20 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
20e30 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
20e40 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
20e50 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
20e60 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76 65 72  s */.};../* Ever
20e70 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  y module impleme
20e80 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73  ntation uses a s
20e90 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66  ubclass of the f
20ea0 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
20eb0 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62  re.** to describ
20ec0 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70  e cursors that p
20ed0 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 69  oint into the vi
20ee0 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
20ef0 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c  are used.** to l
20f00 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20  oop through the 
20f10 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20  virtual table.  
20f20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61  Cursors are crea
20f30 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ted using the.**
20f40 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
20f50 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61   the module.  Ea
20f60 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ch module implem
20f70 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65  entation will de
20f80 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  fine.** the cont
20f90 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20  ent of a cursor 
20fa0 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69  structure to sui
20fb0 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e  t its own needs.
20fc0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65  .**.** This supe
20fd0 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e  rclass exists in
20fe0 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65   order to define
20ff0 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63   fields of the c
21000 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72  ursor that.** ar
21010 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20  e common to all 
21020 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
21030 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
21040 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
21050 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  .  sqlite3_vtab 
21060 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20  *pVtab;      /* 
21070 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66  Virtual table of
21080 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a   this cursor */.
21090 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
210a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
210b0 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
210c0 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
210d0 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
210e0 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74 65  *.** The xCreate
210f0 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65   and xConnect me
21100 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75 6c  thods of a modul
21110 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77  e use the follow
21120 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64 65  ing API.** to de
21130 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74  clare the format
21140 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20   (the names and 
21150 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65  datatypes of the
21160 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20   columns) of.** 
21170 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
21180 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e  es they implemen
21190 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
211a0 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73  3_declare_vtab(s
211b0 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
211c0 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62 6c  har *zCreateTabl
211d0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72 74 75  e);../*.** Virtu
211e0 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72  al tables can pr
211f0 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76  ovide alternativ
21200 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
21210 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  s of functions.*
21220 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46 69 6e  * using the xFin
21230 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64  dFunction method
21240 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65  .  But global ve
21250 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20  rsions of those 
21260 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73  functions.** mus
21270 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72  t exist in order
21280 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65   to be overloade
21290 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  d..**.** This AP
212a0 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67  I makes sure a g
212b0 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66  lobal version of
212c0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
212d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
212e0 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72   name and number
212f0 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65   of parameters e
21300 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75  xists.  If no su
21310 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73  ch function exis
21320 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69  ts.** before thi
21330 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c  s API is called,
21340 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20   a new function 
21350 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65  is created.  The
21360 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
21370 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75  ** of the new fu
21380 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61  nction always ca
21390 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f  uses an exceptio
213a0 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20  n to be thrown. 
213b0 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66   So.** the new f
213c0 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67  unction is not g
213d0 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67  ood for anything
213e0 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73   by itself.  Its
213f0 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65   only.** purpose
21400 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63   is to be a plac
21410 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f  e-holder functio
21420 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  n that can be ov
21430 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76  erloaded.** by v
21440 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a  irtual tables..*
21450 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73 68  *.** This API sh
21460 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72  ould be consider
21470 65 64 20 70 61 72 74 20 6f 66 20 74 68 65 20 76  ed part of the v
21480 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74  irtual table int
21490 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68  erface,.** which
214a0 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
214b0 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20   and subject to 
214c0 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
214d0 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f  qlite3_overload_
214e0 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33  function(sqlite3
214f0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
21500 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41  FuncName, int nA
21510 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  rg);../*.** The 
21520 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
21530 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
21540 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64  echanism defined
21550 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a   above (back up.
21560 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20  ** to a comment 
21570 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c  remarkably simil
21580 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20  ar to this one) 
21590 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
215a0 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
215b0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
215c0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
215d0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
215e0 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
215f0 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
21600 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
21610 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
21620 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
21630 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
21640 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
21650 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
21660 73 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69  stablizes, we wi
21670 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
21680 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
21690 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
216a0 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
216b0 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
216c0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45  ent..**.****** E
216d0 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75  XPERIMENTAL - su
216e0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
216f0 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a  without notice *
21700 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f  *************.*/
21710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21720 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
21730 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a   Open BLOB.**.**
21740 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
21750 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 70  the following op
21760 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 69  aque structure i
21770 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a 20 72 65  s used to .** re
21780 70 72 65 73 65 6e 74 20 61 6e 20 62 6c 6f 62 2d  present an blob-
21790 68 61 6e 64 6c 65 2e 20 20 41 20 62 6c 6f 62 2d  handle.  A blob-
217a0 68 61 6e 64 6c 65 20 69 73 20 63 72 65 61 74 65  handle is create
217b0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
217c0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
217d0 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  d destroyed by [
217e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
217f0 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  se()]..** The [s
21800 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
21810 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
21820 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69  _blob_write()] i
21830 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e  nterfaces.** can
21840 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64   be used to read
21850 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20   or write small 
21860 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74  subsections of t
21870 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68 65 20  he blob..** The 
21880 5b 73 71 6c 74 69 65 33 5f 62 6c 6f 62 5f 73 69  [sqltie3_blob_si
21890 7a 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ze()] interface 
218a0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
218b0 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c 6f 62 20   of the.** blob 
218c0 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70  in bytes..*/.typ
218d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
218e0 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33  te3_blob sqlite3
218f0 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _blob;../*.** CA
21900 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42  PI3REF: Open A B
21910 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e  LOB For Incremen
21920 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 4f 70  tal I/O.**.** Op
21930 65 6e 20 61 20 68 61 6e 64 6c 65 20 74 6f 20 74  en a handle to t
21940 68 65 20 62 6c 6f 62 20 6c 6f 63 61 74 65 64 20  he blob located 
21950 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20 63 6f  in row iRow,, co
21960 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 0a 2a  lumn zColumn, .*
21970 2a 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69  * table zTable i
21980 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 2e 20  n database zDb. 
21990 69 2e 65 2e 20 74 68 65 20 73 61 6d 65 20 62 6c  i.e. the same bl
219a0 6f 62 20 74 68 61 74 20 77 6f 75 6c 64 0a 2a 2a  ob that would.**
219b0 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a   be selected by:
219c0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
219d0 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75      SELECT zColu
219e0 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62  mn FROM zDb.zTab
219f0 6c 65 20 57 48 45 52 45 20 72 6f 77 69 64 20 3d  le WHERE rowid =
21a00 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   iRow;.** </pre>
21a10 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c  .**.** If the fl
21a20 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  ags parameter is
21a30 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 62   non-zero, the b
21a40 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  lob is opened fo
21a50 72 20 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20 77  r .** read and w
21a60 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20  rite access. If 
21a70 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
21a80 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66  blob is opened f
21a90 6f 72 20 72 65 61 64 20 0a 2a 2a 20 61 63 63 65  or read .** acce
21aa0 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  ss..**.** On suc
21ab0 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  cess, [SQLITE_OK
21ac0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
21ad0 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73  d the new .** [s
21ae0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
21af0 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72  ob handle] is wr
21b00 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62  itten to *ppBlob
21b10 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 61  ..** Otherwise a
21b20 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  n error code is 
21b30 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a 2a  returned and .**
21b40 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74 74   any value writt
21b50 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68  en to *ppBlob sh
21b60 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
21b70 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a   by the caller..
21b80 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
21b90 20 73 65 74 73 20 74 68 65 20 64 61 74 61 62 61   sets the databa
21ba0 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f 72 20  se-handle error 
21bb0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
21bc0 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76  .** accessible v
21bd0 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
21be0 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ode()] and [sqli
21bf0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
21c00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
21c10 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74  ob_open(.  sqlit
21c20 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  e3*,.  const cha
21c30 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20  r *zDb,.  const 
21c40 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20  char *zTable,.  
21c50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
21c60 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69  umn,.  sqlite3_i
21c70 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74  nt64 iRow,.  int
21c80 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65   flags,.  sqlite
21c90 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a  3_blob **ppBlob.
21ca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21cb0 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 4c 4f  EF:  Close A BLO
21cc0 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 43  B Handle.**.** C
21cd0 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b 73 71  lose an open [sq
21ce0 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f  lite3_blob | blo
21cf0 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2f 0a 69 6e  b handle]..*/.in
21d00 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63  t sqlite3_blob_c
21d10 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  lose(sqlite3_blo
21d20 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
21d30 49 33 52 45 46 3a 20 20 52 65 74 75 72 6e 20 54  I3REF:  Return T
21d40 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70  he Size Of An Op
21d50 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 52 65  en BLOB.**.** Re
21d60 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 69 6e  turn the size in
21d70 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c   bytes of the bl
21d80 6f 62 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ob accessible vi
21d90 61 20 74 68 65 20 6f 70 65 6e 20 0a 2a 2a 20 5b  a the open .** [
21da0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
21db0 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73  lob-handle] pass
21dc0 65 64 20 61 73 20 61 6e 20 61 72 67 75 6d 65 6e  ed as an argumen
21dd0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
21de0 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c  3_blob_bytes(sql
21df0 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
21e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
21e10 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41  Read Data From A
21e20 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61   BLOB Incrementa
21e30 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  lly.**.** This f
21e40 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20  unction is used 
21e50 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f  to read data fro
21e60 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73  m an open .** [s
21e70 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
21e80 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20  ob-handle] into 
21e90 61 20 63 61 6c 6c 65 72 20 73 75 70 70 6c 69 65  a caller supplie
21ea0 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20 62  d buffer..** n b
21eb0 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
21ec0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66   copied into buf
21ed0 66 65 72 0a 2a 2a 20 7a 20 66 72 6f 6d 20 74 68  fer.** z from th
21ee0 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61  e open blob, sta
21ef0 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20  rting at offset 
21f00 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 4f  iOffset..**.** O
21f10 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54  n success, SQLIT
21f20 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
21f30 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20  . Otherwise, an 
21f40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
21f50 52 20 7c 20 53 51 4c 69 74 65 20 65 72 72 6f 72  R | SQLite error
21f60 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
21f70 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
21f80 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72  AD | extended er
21f90 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
21fa0 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  urned..*/.int sq
21fb0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
21fc0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
21fd0 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20  void *z, int n, 
21fe0 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f  int iOffset);../
21ff0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
22000 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20  Write Data Into 
22010 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
22020 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ally.**.** This 
22030 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
22040 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69   to write data i
22050 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20  nto an open .** 
22060 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
22070 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 66 72 6f  blob-handle] fro
22080 6d 20 61 20 75 73 65 72 20 73 75 70 70 6c 69 65  m a user supplie
22090 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20 62  d buffer..** n b
220a0 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
220b0 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65   copied from the
220c0 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69 6e 74   buffer.** point
220d0 65 64 20 74 6f 20 62 79 20 7a 20 69 6e 74 6f 20  ed to by z into 
220e0 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73  the open blob, s
220f0 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
22100 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a  t iOffset..**.**
22110 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
22120 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e  _blob | blob-han
22130 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 74  dle] passed as t
22140 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
22150 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 70 65  t.** was not ope
22160 6e 65 64 20 66 6f 72 20 77 72 69 74 69 6e 67 20  ned for writing 
22170 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (the flags param
22180 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
22190 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  _blob_open()].**
221a0 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20 74 68 69  * was zero), thi
221b0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
221c0 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f  ns [SQLITE_READO
221d0 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  NLY]..**.** This
221e0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e   function may on
221f0 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f  ly modify the co
22200 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 62 6c  ntents of the bl
22210 6f 62 2c 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74  ob, it is.** not
22220 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63   possible to inc
22230 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f  rease the size o
22240 66 20 61 20 62 6c 6f 62 20 75 73 69 6e 67 20 74  f a blob using t
22250 68 69 73 20 41 50 49 2e 20 49 66 0a 2a 2a 20 6f  his API. If.** o
22260 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73  ffset iOffset is
22270 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62 79 74   less than n byt
22280 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20  es from the end 
22290 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a  of the blob, .**
222a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
222b0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
222c0 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74  no data is writt
222d0 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  en..**.** On suc
222e0 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20  cess, SQLITE_OK 
222f0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68  is returned. Oth
22300 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b  erwise, an .** [
22310 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 53  SQLITE_ERROR | S
22320 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65  QLite error code
22330 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49  ] or an.** [SQLI
22340 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
22350 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
22360 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
22370 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22380 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69  _blob_write(sqli
22390 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73  te3_blob *, cons
223a0 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e  t void *z, int n
223b0 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a  , int iOffset);.
223c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
223d0 20 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53    Virtual File S
223e0 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a  ystem Objects.**
223f0 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69  .** A virtual fi
22400 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69  lesystem (VFS) i
22410 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  s an [sqlite3_vf
22420 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61  s] object.** tha
22430 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f  t SQLite uses to
22440 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74   interact.** wit
22450 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  h the underlying
22460 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
22470 6d 2e 20 20 4d 6f 73 74 20 62 75 69 6c 64 73 20  m.  Most builds 
22480 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73  come with a.** s
22490 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46  ingle default VF
224a0 53 20 74 68 61 74 20 69 73 20 61 70 70 72 6f 70  S that is approp
224b0 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f  riate for the ho
224c0 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20  st computer..** 
224d0 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 62 65  New VFSes can be
224e0 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
224f0 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 20 63  existing VFSes c
22500 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65 72  an be unregister
22510 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  ed..** The follo
22520 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20  wing interfaces 
22530 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a  are provided..**
22540 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22550 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72  vfs_find() inter
22560 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
22570 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20  ointer to a VFS 
22580 67 69 76 65 6e 20 69 74 73 0a 2a 2a 20 6e 61 6d  given its.** nam
22590 65 2e 20 20 4e 61 6d 65 73 20 61 72 65 20 63 61  e.  Names are ca
225a0 73 65 20 73 65 6e 73 69 74 69 76 65 2e 20 20 49  se sensitive.  I
225b0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61  f there is no ma
225c0 74 63 68 2c 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  tch, a NULL.** p
225d0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
225e0 65 64 2e 20 20 49 66 20 7a 56 66 73 4e 61 6d 65  ed.  If zVfsName
225f0 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
22600 65 20 64 65 66 61 75 6c 74 20 0a 2a 2a 20 56 46  e default .** VF
22610 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  S is returned.  
22620 49 66 20 61 20 76 61 6c 69 64 20 56 46 53 20 70  If a valid VFS p
22630 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
22640 65 64 2c 20 69 74 73 0a 2a 2a 20 76 66 73 4d 75  ed, its.** vfsMu
22650 74 65 78 20 66 69 65 6c 64 20 77 69 6c 6c 20 68  tex field will h
22660 61 76 65 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  ave been initial
22670 69 7a 65 64 20 61 6e 64 20 6e 52 65 66 20 77 69  ized and nRef wi
22680 6c 6c 20 62 65 0a 2a 2a 20 67 72 65 61 74 65 72  ll be.** greater
22690 20 74 68 61 6e 20 7a 65 72 6f 2e 20 20 54 68 65   than zero.  The
226a0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 6c   sqlite3_vfs_rel
226b0 65 61 73 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  ease() function 
226c0 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 75 73 65  should.** be use
226d0 64 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  d to release the
226e0 20 56 46 53 20 77 68 65 6e 20 69 74 20 69 73 20   VFS when it is 
226f0 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
22700 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65  ..**.** New VFSe
22710 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
22720 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66   with sqlite3_vf
22730 73 5f 72 65 67 69 73 74 65 72 28 29 2e 20 20 45  s_register().  E
22740 61 63 68 0a 2a 2a 20 6e 65 77 20 56 46 53 20 62  ach.** new VFS b
22750 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75  ecomes the defau
22760 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d 61  lt VFS if the ma
22770 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73  keDflt flag is s
22780 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20  et..** The same 
22790 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73  VFS can be regis
227a0 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
227b0 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a  imes without inj
227c0 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20  ury..** To make 
227d0 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20  an existing VFS 
227e0 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74  into the default
227f0 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69   VFS, register i
22800 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20  t again.** with 
22810 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
22820 67 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 55 6e  g set..** .** Un
22830 72 65 67 69 73 74 65 72 20 61 20 56 46 53 20 77  register a VFS w
22840 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ith the sqlite3_
22850 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
22860 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
22870 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
22880 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65  S is unregistere
22890 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69  d, another VFS i
228a0 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74  s chosen as.** t
228b0 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65  he default.  The
228c0 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20   choice for the 
228d0 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74  new VFS is arbit
228e0 72 61 72 79 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  rary..*/.sqlite3
228f0 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66  _vfs *sqlite3_vf
22900 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61  s_find(const cha
22910 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e  r *zVfsName);.in
22920 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  t sqlite3_vfs_re
22930 6c 65 61 73 65 28 73 71 6c 69 74 65 33 5f 76 66  lease(sqlite3_vf
22940 73 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  s*);.int sqlite3
22950 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71  _vfs_register(sq
22960 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
22970 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73  makeDflt);.int s
22980 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
22990 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66  ister(sqlite3_vf
229a0 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s*);../*.** CAPI
229b0 33 52 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a  3REF: Mutexes.**
229c0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
229d0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72  ore uses these r
229e0 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65  outines for thre
229f0 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a  ad.** synchroniz
22a00 61 74 69 6f 6e 2e 20 20 54 68 6f 75 67 68 20 74  ation.  Though t
22a10 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64  hey are intended
22a20 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
22a30 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20   use by SQLite, 
22a40 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  code that links 
22a50 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69  against SQLite i
22a60 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74  s.** permitted t
22a70 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65  o use any of the
22a80 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
22a90 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f  ** The SQLite so
22aa0 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69  urce code contai
22ab0 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  ns multiple impl
22ac0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 0a 2a 2a 20  ementations .** 
22ad0 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72  of these mutex r
22ae0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 63 61 6e  outines that can
22af0 20 62 65 20 73 65 6c 65 63 74 65 64 20 61 74 20   be selected at 
22b00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
22b10 62 79 20 64 65 66 69 6e 69 6e 67 20 6f 6e 65 20  by defining one 
22b20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
22b30 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
22b40 6d 61 63 72 6f 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  macros:.**.** <u
22b50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  l>.** <li>   SQL
22b60 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41  ITE_MUTEX_PTHREA
22b70 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49  D.** <li>   SQLI
22b80 54 45 5f 4d 55 54 45 58 5f 57 49 4e 33 32 0a 2a  TE_MUTEX_WIN32.*
22b90 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
22ba0 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 6c  MUTEX_NOOP.** <l
22bb0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
22bc0 58 5f 41 50 50 44 45 46 0a 2a 2a 20 3c 2f 75 6c  X_APPDEF.** </ul
22bd0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 6e 6f 6e 65 20  >.**.** If none 
22be0 6f 66 20 74 68 65 20 61 62 6f 76 65 20 6d 61 63  of the above mac
22bf0 72 6f 73 20 69 73 20 64 65 66 69 6e 65 64 2c 20  ros is defined, 
22c00 74 68 65 20 63 6f 64 65 20 75 73 65 73 0a 2a 2a  the code uses.**
22c10 20 61 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65   a default imple
22c20 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
22c30 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d  .** The SQLITE_M
22c40 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d  UTEX_NOOP implem
22c50 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65  entation is a se
22c60 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 0a 2a  t of routines .*
22c70 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72  * that does no r
22c80 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20  eal locking and 
22c90 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
22ca0 6f 72 20 75 73 65 20 69 6e 20 0a 2a 2a 20 61 20  or use in .** a 
22cb0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20  single-threaded 
22cc0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20  application..** 
22cd0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 49 54  .** If the SQLIT
22ce0 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 69  E_MUTEX_APPDEF i
22cf0 73 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  s defined, then 
22d00 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  no mutex.** impl
22d10 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e  ementation is in
22d20 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20  cluded with the 
22d30 6c 69 62 72 61 72 79 2e 20 20 54 68 65 0a 2a 2a  library.  The.**
22d40 20 6d 75 74 65 78 20 69 6e 74 65 72 66 61 63 65   mutex interface
22d50 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
22d60 64 20 61 62 6f 76 65 20 61 72 65 20 65 78 74 65  d above are exte
22d70 72 6e 61 6c 0a 2a 2a 20 72 65 66 65 72 65 6e 63  rnal.** referenc
22d80 65 73 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  es in the SQLite
22d90 20 6c 69 62 72 61 72 79 20 66 6f 72 20 77 68 69   library for whi
22da0 63 68 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ch implementatio
22db0 6e 73 0a 2a 2a 20 6d 75 73 74 20 62 65 20 70 72  ns.** must be pr
22dc0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 61 70  ovided by the ap
22dd0 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  plication..**.**
22de0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
22df0 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  ex_alloc() routi
22e00 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e  ne allocates a n
22e10 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20  ew.** mutex and 
22e20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
22e30 72 20 74 6f 20 69 74 2e 20 20 49 66 20 69 74 20  r to it.  If it 
22e40 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20  returns NULL.** 
22e50 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20  that means that 
22e60 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f  a mutex could no
22e70 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20  t be allocated. 
22e80 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
22e90 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b  unwind its stack
22ea0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65   and return an e
22eb0 72 72 6f 72 2e 20 20 54 68 65 20 61 72 67 75 6d  rror.  The argum
22ec0 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
22ed0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
22ee0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  is one of these 
22ef0 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
22f00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
22f10 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
22f20 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e  TEX_FAST.** <li>
22f30 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52    SQLITE_MUTEX_R
22f40 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  ECURSIVE.** <li>
22f50 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
22f60 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20  TATIC_MASTER.** 
22f70 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
22f80 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a  EX_STATIC_MEM.**
22f90 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
22fa0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a  TEX_STATIC_MEM2.
22fb0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
22fc0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
22fd0 47 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  G.** </ul>.**.**
22fe0 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63   The first two c
22ff0 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73  onstants cause s
23000 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
23010 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a  oc() to create.*
23020 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20  * a new mutex.  
23030 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73  The new mutex is
23040 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20   recursive when 
23050 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
23060 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65  URSIVE.** is use
23070 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73  d but not necess
23080 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51  arily so when SQ
23090 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
230a0 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20  is used..** The 
230b0 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
230c0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
230d0 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73  ed to make a dis
230e0 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
230f0 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  een SQLITE_MUTEX
23100 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53  _RECURSIVE and S
23110 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
23120 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   if it does.** n
23130 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 42 75 74  ot want to.  But
23140 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
23150 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75  y request a recu
23160 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a  rsive mutex in.*
23170 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74  * cases where it
23180 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e   really needs on
23190 65 2e 20 20 49 66 20 61 20 66 61 73 74 65 72 20  e.  If a faster 
231a0 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75  non-recursive mu
231b0 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
231c0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
231d0 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70  le on the host p
231e0 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74  latform, the mut
231f0 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20  ex subsystem.** 
23200 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 63  might return suc
23210 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73  h a mutex in res
23220 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f  ponse to SQLITE_
23230 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a  MUTEX_FAST..**.*
23240 2a 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f  * The other allo
23250 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74  wed parameters t
23260 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
23270 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74  alloc() each ret
23280 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  urn.** a pointer
23290 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65   to a static pre
232a0 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20  existing mutex. 
232b0 20 54 68 72 65 65 20 73 74 61 74 69 63 20 6d 75   Three static mu
232c0 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  texes are.** use
232d0 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  d by the current
232e0 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
232f0 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  te.  Future vers
23300 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
23310 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69  * may add additi
23320 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65  onal static mute
23330 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74  xes.  Static mut
23340 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74  exes are for int
23350 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
23360 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70  SQLite only.  Ap
23370 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
23380 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78  use SQLite mutex
23390 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65  es should.** use
233a0 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69   only the dynami
233b0 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e  c mutexes return
233c0 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54  ed by SQLITE_MUT
233d0 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51  EX_FAST or.** SQ
233e0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
233f0 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  SIVE..**.** Note
23400 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20   that if one of 
23410 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  the dynamic mute
23420 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51  x parameters (SQ
23430 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a  LITE_MUTEX_FAST.
23440 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54  ** or SQLITE_MUT
23450 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73  EX_RECURSIVE) is
23460 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74   used then sqlit
23470 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
23480 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69  .** returns a di
23490 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e  fferent mutex on
234a0 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 42 75   every call.  Bu
234b0 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63  t for the static
234c0 20 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73   .** mutex types
234d0 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78  , the same mutex
234e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20   is returned on 
234f0 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20  every call that 
23500 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  has.** the same 
23510 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  type number..**.
23520 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
23530 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74  utex_free() rout
23540 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  ine deallocates 
23550 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  a previously.** 
23560 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69  allocated dynami
23570 63 20 6d 75 74 65 78 2e 20 20 53 51 4c 69 74 65  c mutex.  SQLite
23580 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64   is careful to d
23590 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a  eallocate every.
235a0 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ** dynamic mutex
235b0 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74   that it allocat
235c0 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63  es.  The dynamic
235d0 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f   mutexes must no
235e0 74 20 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65 20  t be in .** use 
235f0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65  when they are de
23600 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65  allocated.  Atte
23610 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f  mpting to deallo
23620 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a  cate a static.**
23630 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69   mutex results i
23640 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
23650 76 69 6f 72 2e 20 20 53 51 4c 69 74 65 20 6e 65  vior.  SQLite ne
23660 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a  ver deallocates.
23670 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65  ** a static mute
23680 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  x..**.** The sql
23690 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
236a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
236b0 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69  utex_try() routi
236c0 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74  nes attempt.** t
236d0 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e  o enter a mutex.
236e0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72    If another thr
236f0 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77  ead is already w
23700 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c  ithin the mutex,
23710 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
23720 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62  x_enter() will b
23730 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33  lock and sqlite3
23740 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c  _mutex_try() wil
23750 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  l return.** SQLI
23760 54 45 5f 42 55 53 59 2e 20 20 54 68 65 20 73 71  TE_BUSY.  The sq
23770 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
23780 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
23790 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a  rns SQLITE_OK.**
237a0 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c   upon successful
237b0 20 65 6e 74 72 79 2e 20 20 4d 75 74 65 78 65 73   entry.  Mutexes
237c0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 53   created using S
237d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
237e0 52 53 49 56 45 20 63 61 6e 0a 2a 2a 20 62 65 20  RSIVE can.** be 
237f0 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  entered multiple
23800 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61   times by the sa
23810 6d 65 20 74 68 72 65 61 64 2e 20 20 49 6e 20 73  me thread.  In s
23820 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a  uch cases the,.*
23830 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20  * mutex must be 
23840 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20  exited an equal 
23850 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
23860 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74  before another t
23870 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74  hread.** can ent
23880 65 72 2e 20 20 49 66 20 74 68 65 20 73 61 6d 65  er.  If the same
23890 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f   thread tries to
238a0 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72   enter any other
238b0 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 0a 2a   kind of mutex.*
238c0 2a 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  * more than once
238d0 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
238e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 20 53  s undefined.   S
238f0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
23900 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68   exhibit.** such
23910 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73   behavior in its
23920 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65   own use of mute
23930 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  xes..**.** The s
23940 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 78 69  qlite3_mutex_exi
23950 74 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74  t() routine exit
23960 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77  s a mutex that w
23970 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
23980 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20   entered by the 
23990 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 54 68  same thread.  Th
239a0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
239b0 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68   undefined if th
239c0 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63  e mutex is not c
239d0 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
239e0 20 6f 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 75   or.** is not cu
239f0 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65  rrently allocate
23a00 64 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  d.  SQLite will 
23a10 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e  never do either.
23a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23a30 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20  e3_mutex_held() 
23a40 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  and sqlite3_mute
23a50 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74  x_notheld() rout
23a60 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65  ines.** are inte
23a70 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  nded for use ins
23a80 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ide assert() sta
23a90 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 79 20 73  tements.  They s
23aa0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
23ab0 74 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 65  true if the mute
23ac0 78 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d  x in their argum
23ad0 65 6e 74 20 69 73 20 68 65 6c 64 20 6f 72 20 6e  ent is held or n
23ae0 6f 74 20 68 65 6c 64 2c 0a 2a 2a 20 72 65 73 70  ot held,.** resp
23af0 65 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65  ectively, by the
23b00 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 2e   current thread.
23b10 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
23b20 69 6f 6e 20 69 73 0a 2a 2a 20 6e 6f 74 20 72 65  ion is.** not re
23b30 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64  quired to provid
23b40 65 64 20 77 6f 72 6b 69 6e 67 20 69 6d 70 6c 65  ed working imple
23b50 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
23b60 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ese.** routines 
23b70 61 73 20 74 68 65 69 72 20 69 6e 74 65 6e 64 65  as their intende
23b80 64 20 75 73 65 20 69 73 20 77 69 74 68 69 6e 20  d use is within 
23b90 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
23ba0 6e 74 73 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 49 66  nts.** only.  If
23bb0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
23bc0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f  ion does not pro
23bd0 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20  vide working.** 
23be0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
23bf0 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 6d  e routines, it m
23c00 75 73 74 20 61 74 20 6c 65 61 73 74 20 70 72 6f  ust at least pro
23c10 76 69 64 65 20 73 74 75 62 73 0a 2a 2a 20 74 68  vide stubs.** th
23c20 61 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  at always return
23c30 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20   true..**.** If 
23c40 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
23c50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
23c60 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ld() is a NULL p
23c70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74  ointer then.** t
23c80 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  he routine shoul
23c90 64 20 72 65 74 75 72 6e 20 31 2e 20 20 54 68 69  d return 1.  Thi
23ca0 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d  s seems counter-
23cb0 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a  intuitive since.
23cc0 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d  ** clearly the m
23cd0 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68  utex cannot be h
23ce0 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e  eld if it does n
23cf0 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74  ot exist.  But t
23d00 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e  he.** the reason
23d10 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20   the mutex does 
23d20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63  not exist is bec
23d30 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 69  ause the build i
23d40 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d  s not.** using m
23d50 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20  utexes.  And we 
23d60 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  do not want the 
23d70 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e  assert() contain
23d80 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20  ing the.** call 
23d90 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
23da0 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c  _held() to fail,
23db0 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   so a non-zero r
23dc0 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20  eturn is.** the 
23dd0 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e  appropriate thin
23de0 67 20 74 6f 20 64 6f 2e 20 20 54 68 65 20 73 71  g to do.  The sq
23df0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
23e00 65 6c 64 28 29 20 0a 2a 2a 20 69 6e 74 65 72 66  eld() .** interf
23e10 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20  ace should also 
23e20 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69  return 1 when gi
23e30 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
23e40 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  er..*/.sqlite3_m
23e50 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75  utex *sqlite3_mu
23e60 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  tex_alloc(int);.
23e70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74  void sqlite3_mut
23e80 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f  ex_free(sqlite3_
23e90 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
23ea0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
23eb0 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  r(sqlite3_mutex*
23ec0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  );.int sqlite3_m
23ed0 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33  utex_try(sqlite3
23ee0 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73  _mutex*);.void s
23ef0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
23f00 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ve(sqlite3_mutex
23f10 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
23f20 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74  mutex_held(sqlit
23f30 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
23f40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
23f50 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  theld(sqlite3_mu
23f60 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tex*);../*.** CA
23f70 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79  PI3REF: Mutex Ty
23f80 70 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  pes.**.** The [s
23f90 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
23fa0 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  oc()] interface 
23fb0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
23fc0 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68  rgument.** which
23fd0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   is one of these
23fe0 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
23ff0 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ts..*/.#define S
24000 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
24010 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
24020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
24030 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 20 20  TEX_RECURSIVE   
24040 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
24050 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
24060 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23  IC_MASTER    2.#
24070 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
24080 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20  TEX_STATIC_MEM  
24090 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74       3  /* sqlit
240a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23  e3_malloc() */.#
240b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
240c0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20  TEX_STATIC_MEM2 
240d0 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
240e0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
240f0 79 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  y() */.#define S
24100 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
24110 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20  IC_PRNG      5  
24120 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  /* sqlite3_rando
24130 6d 28 29 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 55  m() */.../*.** U
24140 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68 61  ndo the hack tha
24150 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61 74  t converts float
24160 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73 20  ing point types 
24170 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a 2a  to integer for.*
24180 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f 63  * builds on proc
24190 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20 66  essors without f
241a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75  loating point su
241b0 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  pport..*/.#ifdef
241c0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
241d0 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 6e  ATING_POINT.# un
241e0 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64 69  def double.#endi
241f0 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  f..#ifdef __cplu
24200 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 20  splus.}  /* End 
24210 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e 20 22  of the 'extern "
24220 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e  C"' block */.#en
24230 64 69 66 0a 23 65 6e 64 69 66 0a                 dif.#endif.