/ Hex Artifact Content
Login

Artifact a1a5bc9e7e63bf73c2bb68be3749dec2bbd8cc44:


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 38 20 32 30 30 37 2f  in,v 1.238 2007/
05f0: 30 38 2f 32 33 20 30 32 3a 34 37 3a 35 33 20 64  08/23 02:47:53 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 33 30 30  L     0x00000300
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 34 30 30  L     0x00000400
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 30 35 30 30        0x00000500
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 30 36 30 30  NAL   0x00000600
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 73 74 72 75 63 74 20 73  ile {.  struct s
45f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
4600: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
4610: 20 4d 65 74 68 6f 64 73 20 61 67 61 69 6e 73 74   Methods against
4620: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 2a   the open file *
4630: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
4640: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
4650: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
4660: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a  Methods Object.*
4670: 2a 0a 2a 2a 20 45 76 65 72 79 20 6f 70 65 6e 20  *.** Every open 
4680: 66 69 6c 65 20 69 6e 20 74 68 65 20 5b 73 71 6c  file in the [sql
4690: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
46a0: 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73 20  method contains 
46b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
46c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
46d0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 62 6a  he following obj
46e0: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
46f0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 0a 2a 2a  t defines the.**
4700: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
4710: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
4720: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 67 61 69   operations agai
4730: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
4740: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  e..**.** The fla
4750: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
4760: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
4770: 6f 66 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 42  of SQLITE_SYNC_B
4780: 41 52 52 49 45 52 2c 0a 2a 2a 20 53 51 4c 49 54  ARRIER,.** SQLIT
4790: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 53  E_SYNC_NORMAL, S
47a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2e  QLITE_SYNC_FULL.
47b0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
47c0: 63 65 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ce means that.**
47d0: 20 64 61 74 61 20 69 73 20 6e 6f 74 20 6e 65 63   data is not nec
47e0: 65 73 73 61 72 69 6c 79 20 73 79 6e 63 65 64 20  essarily synced 
47f0: 74 6f 20 64 69 73 6b 20 63 6f 6d 70 6c 65 74 65  to disk complete
4800: 6c 79 2c 20 6f 6e 6c 79 20 74 68 61 74 0a 2a 2a  ly, only that.**
4810: 20 61 6c 6c 20 77 72 69 74 65 73 20 74 68 61 74   all writes that
4820: 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 74 68   occur before th
4830: 65 20 73 79 6e 63 20 63 6f 6d 70 6c 65 74 65 20  e sync complete 
4840: 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 77 72  before any.** wr
4850: 69 74 65 73 20 74 68 61 74 20 6f 63 63 75 72 20  ites that occur 
4860: 61 66 74 65 72 20 74 68 65 20 73 79 6e 63 2e 20  after the sync. 
4870: 20 54 68 65 20 73 65 63 6f 6e 64 20 66 6c 61 67   The second flag
4880: 20 69 73 20 74 68 65 0a 2a 2a 20 6e 6f 72 6d 61   is the.** norma
4890: 6c 20 66 73 79 6e 63 28 29 2e 20 20 54 68 65 20  l fsync().  The 
48a0: 74 68 69 72 64 20 66 6c 61 67 20 69 73 20 61 20  third flag is a 
48b0: 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS-X style fulls
48c0: 79 6e 63 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ync..** The SQLI
48d0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66 6c 61  TE_SYNC_DATA fla
48e0: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
48f0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
4900: 74 20 6f 6e 6c 79 0a 2a 2a 20 74 68 65 20 64 61  t only.** the da
4910: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 20 61  ta of the file a
4920: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
4930: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
4940: 63 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  ced..** .** The 
4950: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
4960: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
4970: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
4980: 6f 66 0a 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f 43  of.** SQLITE_LOC
4990: 4b 5f 4e 4f 4e 45 2c 20 53 51 4c 49 54 45 5f 4c  K_NONE, SQLITE_L
49a0: 4f 43 4b 5f 52 45 41 44 2c 20 53 51 4c 49 54 45  OCK_READ, SQLITE
49b0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 2c 0a  _LOCK_RESERVED,.
49c0: 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ** SQLITE_LOCK_P
49d0: 45 4e 44 49 4e 47 2c 20 6f 72 20 53 51 4c 49 54  ENDING, or SQLIT
49e0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
49f0: 2e 20 20 78 4c 6f 63 6b 28 29 0a 2a 2a 20 69 6e  .  xLock().** in
4a00: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
4a10: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
4a20: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
4a30: 20 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52   .** The xCheckR
4a40: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
4a50: 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f  thod looks.** to
4a60: 20 73 65 65 20 69 66 20 61 6e 79 20 64 61 74 61   see if any data
4a70: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
4a80: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 0a   either in this.
4a90: 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  ** process or in
4aa0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
4ab0: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
4ac0: 61 6e 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20  an RESERVED,.** 
4ad0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
4ae0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
4af0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
4b00: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
4b10: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
4b20: 73 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 6e  s and false if n
4b30: 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 78 42 72 65 61  ot..** .** xBrea
4b40: 6b 4c 6f 63 6b 28 29 20 61 74 74 65 6d 70 74 73  kLock() attempts
4b50: 20 74 6f 20 62 72 65 61 6b 20 61 20 6c 6f 63 6b   to break a lock
4b60: 20 68 65 6c 64 20 62 79 20 61 6e 6f 74 68 65 72   held by another
4b70: 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69   process..** Thi
4b80: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
4b90: 20 72 65 6d 6f 76 65 20 61 20 73 74 61 6c 65 20   remove a stale 
4ba0: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 2c 20 66  dot-file lock, f
4bb0: 6f 72 20 65 78 61 6d 70 6c 65 2e 0a 2a 2a 20 49  or example..** I
4bc0: 74 20 72 65 74 75 72 6e 73 20 30 20 6f 6e 20 73  t returns 0 on s
4bd0: 75 63 63 65 73 73 20 61 6e 64 20 6e 6f 6e 2d 7a  uccess and non-z
4be0: 65 72 6f 20 66 6f 72 20 61 20 66 61 69 6c 75 72  ero for a failur
4bf0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  e..**.** The xSe
4c00: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
4c10: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
4c20: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
4c30: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
4c40: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
4c50: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
4c60: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
4c70: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
4c80: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
4c90: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
4ca0: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
4cb0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
4cc0: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
4cd0: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
4ce0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
4cf0: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
4d00: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
4d10: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
4d20: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
4d30: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
4d40: 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  li> SQLITE_IOCAP
4d50: 5f 41 54 4f 4d 49 43 0a 2a 2a 20 3c 6c 69 3e 20  _ATOMIC.** <li> 
4d60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4d70: 4d 49 43 35 31 32 0a 2a 2a 20 3c 6c 69 3e 20 53  MIC512.** <li> S
4d80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4d90: 49 43 31 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c  IC1K.** <li> SQL
4da0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
4db0: 32 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54  2K.** <li> SQLIT
4dc0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
4dd0: 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f  .** <li> SQLITE_
4de0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 0a 2a  IOCAP_ATOMIC8K.*
4df0: 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f  * <li> SQLITE_IO
4e00: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 0a 2a 2a  CAP_ATOMIC16K.**
4e10: 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43   <li> SQLITE_IOC
4e20: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 0a 2a 2a 20  AP_ATOMIC32K.** 
4e30: 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41  <li> SQLITE_IOCA
4e40: 50 5f 41 54 4f 4d 49 43 36 34 4b 0a 2a 2a 20 3c  P_ATOMIC64K.** <
4e50: 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  li> SQLITE_IOCAP
4e60: 5f 53 41 46 45 5f 41 50 50 45 4e 44 0a 2a 2a 20  _SAFE_APPEND.** 
4e70: 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41  <li> SQLITE_IOCA
4e80: 50 5f 53 45 51 55 45 4e 54 49 41 4c 0a 2a 2a 20  P_SEQUENTIAL.** 
4e90: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
4ea0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4eb0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
4ec0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
4ed0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
4ee0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
4ef0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
4f00: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
4f10: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
4f20: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
4f30: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
4f40: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
4f50: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
4f60: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
4f70: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
4f80: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
4f90: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
4fa0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
4fb0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
4fc0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
4fd0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
4fe0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
4ff0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
5000: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
5010: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
5020: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
5030: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
5040: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
5050: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
5060: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
5070: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
5080: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
5090: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
50a0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
50b0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
50c0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
50d0: 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
50e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
50f0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
5100: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
5110: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
5120: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
5130: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
5140: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
5150: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
5160: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
5170: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
5180: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 5f 69 6e   iAmt, sqlite_in
5190: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
51a0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
51b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
51c0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
51d0: 2c 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 69  , sqlite_int64 i
51e0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
51f0: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
5200: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 5f  3_file*, sqlite_
5210: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
5220: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
5230: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
5240: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
5250: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
5260: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 5f  3_file*, sqlite_
5270: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
5280: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
5290: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
52a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
52b0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
52c0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
52d0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
52e0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
52f0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 72  e*);.  int (*xBr
5300: 65 61 6b 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  eakLock)(sqlite3
5310: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
5320: 2a 78 4c 6f 63 6b 53 74 61 74 65 29 28 73 71 6c  *xLockState)(sql
5330: 69 74 65 33 5f 66 69 6c 65 20 2a 29 3b 0a 20 20  ite3_file *);.  
5340: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
5350: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
5360: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
5370: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
5380: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
5390: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
53a0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
53b0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
53c0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
53d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
53e0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
53f0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
5400: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
5410: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
5420: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
5430: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
5440: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
5450: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
5460: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
5470: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
5480: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
5490: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
54a0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
54b0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
54c0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
54d0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
54e0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
54f0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
5500: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
5510: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
5520: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
5530: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
5540: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
5550: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
5560: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
5570: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
5580: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
5590: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
55a0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
55b0: 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a  ce between the.*
55c0: 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  * SQLite core an
55d0: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
55e0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
55f0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
5600: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
5610: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
5620: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
5630: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
5640: 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20  ** The iVersion 
5650: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
5660: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
5670: 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74 75 72  larger for futur
5680: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
5690: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
56a0: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
56b0: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
56c0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
56d0: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
56e0: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
56f0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
5700: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
5710: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
5720: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
5730: 65 33 5f 66 69 6c 65 0a 2a 2a 20 73 74 72 75 63  e3_file.** struc
5740: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
5750: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
5760: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
5770: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
5780: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
5790: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  s VFS..**.** The
57a0: 20 6e 52 65 66 20 66 69 65 6c 64 20 69 73 20 69   nRef field is i
57b0: 6e 63 72 65 6d 65 6e 74 65 64 20 61 6e 64 20 64  ncremented and d
57c0: 65 63 72 65 6d 65 6e 74 65 64 20 62 79 20 53 51  ecremented by SQ
57d0: 4c 69 74 65 20 74 6f 20 6b 65 65 70 0a 2a 2a 20  Lite to keep.** 
57e0: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
57f0: 62 65 72 20 6f 66 20 75 73 65 72 73 20 6f 66 20  ber of users of 
5800: 74 68 65 20 56 46 53 2e 20 20 54 68 69 73 20 66  the VFS.  This f
5810: 69 65 6c 64 20 61 6e 64 0a 2a 2a 20 76 66 73 4d  ield and.** vfsM
5820: 75 74 65 78 2c 20 70 4e 65 78 74 2c 20 61 6e 64  utex, pNext, and
5830: 20 70 50 72 65 76 20 61 72 65 20 74 68 65 20 6f   pPrev are the o
5840: 6e 6c 79 20 66 69 65 6c 64 73 20 69 6e 20 74 68  nly fields in th
5850: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a  e sqlite3_vfs .*
5860: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
5870: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
5880: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
5890: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
58a0: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
58b0: 74 68 65 73 65 20 66 69 65 6c 64 73 20 77 68 69  these fields whi
58c0: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
58d0: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
58e0: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
58f0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
5900: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
5910: 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 73   fields of the s
5920: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
5930: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
5940: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
5950: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 0a 2a 2a  gistered..** .**
5960: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   The sqlite3_vfs
5970: 2e 76 66 73 4d 75 74 65 78 20 69 73 20 61 20 6d  .vfsMutex is a m
5980: 75 74 65 78 20 75 73 65 64 20 62 79 20 74 68 65  utex used by the
5990: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a   OS interface..*
59a0: 2a 20 49 74 20 73 68 6f 75 6c 64 20 69 6e 69 74  * It should init
59b0: 69 61 6c 6c 79 20 62 65 20 4e 55 4c 4c 2e 20 20  ially be NULL.  
59c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 69 74  SQLite will init
59d0: 69 61 6c 69 7a 65 20 74 68 69 73 20 66 69 65 6c  ialize this fiel
59e0: 64 0a 2a 2a 20 75 73 69 6e 67 20 73 71 6c 69 74  d.** using sqlit
59f0: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
5a00: 20 75 70 6f 6e 20 66 69 72 73 74 20 75 73 65 20   upon first use 
5a10: 6f 66 20 74 68 65 20 61 64 61 70 74 6f 72 0a 2a  of the adaptor.*
5a20: 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6f 70 65  * by sqlite3_ope
5a30: 6e 5f 76 32 28 29 20 61 6e 64 20 77 69 6c 6c 20  n_v2() and will 
5a40: 64 65 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6d  deallocate the m
5a50: 75 74 65 78 20 77 68 65 6e 20 74 68 65 0a 2a 2a  utex when the.**
5a60: 20 6c 61 73 74 20 75 73 65 72 20 63 6c 6f 73 65   last user close
5a70: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
5a80: 64 73 2c 20 76 66 73 4d 75 74 65 78 20 77 69 6c  ds, vfsMutex wil
5a90: 6c 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a  l be allocated.*
5aa0: 2a 20 77 68 65 6e 20 6e 52 65 66 20 74 72 61 6e  * when nRef tran
5ab0: 73 69 74 69 6f 6e 73 20 66 72 6f 6d 20 30 20 74  sitions from 0 t
5ac0: 6f 20 31 20 61 6e 64 20 77 69 6c 6c 20 62 65 20  o 1 and will be 
5ad0: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
5ae0: 0a 2a 2a 20 6e 52 65 66 20 74 72 61 6e 73 69 74  .** nRef transit
5af0: 69 6f 6e 73 20 66 72 6f 6d 20 31 20 74 6f 20 30  ions from 1 to 0
5b00: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
5b10: 65 64 20 76 66 73 20 6d 6f 64 75 6c 65 73 20 61  ed vfs modules a
5b20: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
5b30: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
5b40: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
5b50: 61 6e 64 20 70 50 72 65 76 20 70 6f 69 6e 74 65  and pPrev pointe
5b60: 72 73 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  rs.  The [sqlite
5b70: 33 5f 72 65 67 69 73 74 65 72 5f 76 66 73 28 29  3_register_vfs()
5b80: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
5b90: 33 5f 75 6e 72 65 67 69 73 74 65 72 5f 76 66 73  3_unregister_vfs
5ba0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
5bb0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
5bc0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
5bd0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
5be0: 71 6c 69 74 65 33 5f 61 63 71 75 69 72 65 5f 76  qlite3_acquire_v
5bf0: 66 73 28 29 5d 20 73 65 61 72 63 68 65 73 20 74  fs()] searches t
5c00: 68 65 0a 2a 2a 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  he.** list..**.*
5c10: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
5c20: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
5c30: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
5c40: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
5c50: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
5c60: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
5c70: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51  odules..**.** SQ
5c80: 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e  Lite will guaran
5c90: 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69  tee that the zFi
5ca0: 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67 20 70 61  lename string pa
5cb0: 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e  ssed to.** xOpen
5cc0: 28 29 20 69 73 20 61 20 66 75 6c 6c 20 70 61 74  () is a full pat
5cd0: 68 6e 61 6d 65 20 61 73 20 67 65 6e 65 72 61 74  hname as generat
5ce0: 65 64 20 62 79 20 78 46 75 6c 6c 50 61 74 68 6e  ed by xFullPathn
5cf0: 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61  ame() and.** tha
5d00: 74 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  t the string wil
5d10: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
5d20: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
5d30: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
5d40: 6c 6c 65 64 2e 20 20 53 6f 20 74 68 65 20 73 71  lled.  So the sq
5d50: 6c 69 74 65 33 5f 66 69 6c 65 20 63 61 6e 20 73  lite3_file can s
5d60: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
5d70: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
5d80: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
5d90: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
5da0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
5db0: 72 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  reason..**.** Th
5dc0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
5dd0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 73 20 61   to xOpen() is a
5de0: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6c 61   copy of the fla
5df0: 67 73 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  gs argument.** t
5e00: 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
5e10: 32 28 29 2e 20 20 49 66 20 73 71 6c 69 74 65 33  2().  If sqlite3
5e20: 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
5e30: 65 33 5f 6f 70 65 6e 31 36 28 29 0a 2a 2a 20 69  e3_open16().** i
5e40: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
5e50: 67 73 20 69 73 20 53 51 4c 49 54 45 5f 4f 50 45  gs is SQLITE_OPE
5e60: 4e 5f 52 45 41 44 57 52 49 54 45 20 7c 20 53 51  N_READWRITE | SQ
5e70: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5e80: 2e 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20  ..** If xOpen() 
5e90: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
5ea0: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
5eb0: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
5ec0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 53 51 4c  o.** include SQL
5ed0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
5ee0: 59 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  Y.  Other bits i
5ef0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
5f00: 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20 0a   be.** set..** .
5f10: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  ** SQLite will a
5f20: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
5f30: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
5f40: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
5f50: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
5f60: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
5f70: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
5f80: 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  .** .** <ul>.** 
5f90: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
5fa0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
5fb0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
5fc0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
5fd0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
5fe0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
5ff0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
6000: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
6010: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
6020: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
6030: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
6050: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f  R_JOURNAL].** </
6060: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ul>.**.** The fi
6070: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
6080: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
6090: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
60a0: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
60b0: 73 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  s the way it dea
60c0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
60d0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
60e0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
60f0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
6100: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
6110: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
6120: 63 6b 2c 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ck, might make.*
6130: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
6140: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
6150: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
6160: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72   this journal ar
6170: 65 0a 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f  e.** also a no-o
6180: 70 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20  p.  Any attempt 
6190: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
61a0: 6e 61 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  nal return SQLIT
61b0: 45 5f 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74  E_IOERR..** Or t
61c0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
61d0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
61e0: 65 20 74 68 65 20 61 20 64 61 74 61 62 61 73 65  e the a database
61f0: 20 66 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65   file will.** be
6200: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
6210: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
6220: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
6230: 20 72 61 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a   random order.**
6240: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
6250: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
6260: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a  cordingly..** .*
6270: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
6280: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
6290: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
62a0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a  gs to the xOpen.
62b0: 2a 2a 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a  ** method:.** .*
62c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
62d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
62e0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
62f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
6300: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
6310: 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 5b  ul>.** .** The [
6320: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
6330: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
6340: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
6350: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
6360: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
6370: 6c 6f 73 65 64 2e 20 20 54 68 69 73 20 77 69 6c  losed.  This wil
6380: 6c 20 61 6c 77 61 79 73 20 62 65 20 73 65 74 20  l always be set 
6390: 66 6f 72 20 54 45 4d 50 20 0a 2a 2a 20 64 61 74  for TEMP .** dat
63a0: 61 62 61 73 65 73 20 61 6e 64 20 6a 6f 75 72 6e  abases and journ
63b0: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
63c0: 6f 75 72 6e 61 6c 73 2e 20 20 54 68 65 20 0a 2a  ournals.  The .*
63d0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  * [SQLITE_OPEN_E
63e0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d  XCLUSIVE] flag m
63f0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
6400: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a  ould be opened.*
6410: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
6420: 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c  access.  This fl
6430: 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c  ag is set for al
6440: 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a  l files except.*
6450: 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64  * for the main d
6460: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
6470: 20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33   .** The sqlite3
6480: 5f 66 69 6c 65 20 73 74 72 75 63 74 75 72 65 20  _file structure 
6490: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
64a0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ird argument to.
64b0: 2a 2a 20 78 4f 70 65 6e 20 69 73 20 61 6c 6c 6f  ** xOpen is allo
64c0: 63 61 74 65 64 20 62 79 20 74 68 65 20 63 61 6c  cated by the cal
64d0: 6c 65 72 2e 20 20 78 4f 70 65 6e 20 6a 75 73 74  ler.  xOpen just
64e0: 20 66 69 6c 6c 73 20 69 74 20 69 6e 2e 20 20 54   fills it in.  T
64f0: 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 20 61 6c 6c  he.** caller all
6500: 6f 63 61 74 65 73 20 61 20 6d 69 6e 69 6d 75 6d  ocates a minimum
6510: 20 6f 66 20 73 7a 4f 73 46 69 6c 65 20 62 79 74   of szOsFile byt
6520: 65 73 20 66 6f 72 20 74 68 65 20 73 71 6c 69 74  es for the sqlit
6530: 65 33 5f 66 69 6c 65 0a 2a 2a 20 73 74 72 75 63  e3_file.** struc
6540: 74 75 72 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  ture..** .** The
6550: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
6560: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
6570: 20 62 65 20 30 20 28 74 6f 20 74 65 73 74 20 66   be 0 (to test f
6580: 6f 72 20 74 68 65 0a 2a 2a 20 65 78 69 73 74 61  or the.** exista
6590: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 29 20 6f  nce of a file) o
65a0: 72 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  r SQLITE_ACCESS_
65b0: 52 45 41 44 57 52 49 54 45 20 74 6f 20 74 65 73  READWRITE to tes
65c0: 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61  t to see.** if a
65d0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
65e0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
65f0: 6f 72 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  or SQLITE_ACCESS
6600: 5f 52 45 41 44 4f 4e 4c 59 0a 2a 2a 20 74 6f 20  _READONLY.** to 
6610: 74 65 73 74 20 74 6f 20 73 65 65 20 69 66 20 61  test to see if a
6620: 20 66 69 6c 65 20 69 73 20 72 65 61 64 2d 6f 6e   file is read-on
6630: 6c 79 2e 20 20 54 68 65 20 66 69 6c 65 20 63 61  ly.  The file ca
6640: 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69 72 65 63  n be a .** direc
6650: 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c  tory..** .** SQL
6660: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
6670: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
6680: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
6690: 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f  yte for.** the o
66a0: 75 74 70 75 74 20 62 75 66 66 65 72 73 20 66 6f  utput buffers fo
66b0: 72 20 78 47 65 74 54 65 6d 70 4e 61 6d 65 20 61  r xGetTempName a
66c0: 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  nd xFullPathname
66d0: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61  ..** .** The xRa
66e0: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
66f0: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  ep(), and xCurre
6700: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61  ntTime() interfa
6710: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73  ces.** are not s
6720: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
6730: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
6740: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
6750: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
6760: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
6770: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
6780: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
6790: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
67a0: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
67b0: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
67c0: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
67d0: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
67e0: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
67f0: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
6800: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
6810: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
6820: 61 6e 64 6f 6d 6e 65 73 73 20 67 65 6e 65 72 61  andomness genera
6830: 74 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c  ted.  The.** xSl
6840: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
6850: 73 65 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  se the calling t
6860: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
6870: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
6880: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
6890: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
68a0: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
68b0: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
68c0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
68d0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
68e0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
68f0: 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a  and.** time..*/.
6900: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
6910: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
6920: 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73  e3_vfs;.struct s
6930: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
6940: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
6950: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
6960: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
6970: 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f  ber */.  int szO
6980: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
6990: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
69a0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
69b0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
69c0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
69d0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
69e0: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
69f0: 74 68 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66  th */.  int nRef
6a00: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
6a10: 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
6a20: 66 65 72 65 6e 63 65 73 20 74 6f 20 74 68 69 73  ferences to this
6a30: 20 73 74 72 75 63 74 75 72 65 20 2a 2f 0a 20 20   structure */.  
6a40: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 76  sqlite3_mutex *v
6a50: 66 73 4d 75 74 65 78 3b 20 2f 2a 20 41 20 6d 75  fsMutex; /* A mu
6a60: 74 65 78 20 66 6f 72 20 74 68 69 73 20 56 46 53  tex for this VFS
6a70: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
6a80: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
6a90: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
6aa0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
6ab0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
6ac0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
6ad0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
6ae0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
6af0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
6b00: 20 20 20 20 20 20 2f 2a 20 41 70 70 6c 69 63 61        /* Applica
6b10: 74 69 6f 6e 20 63 6f 6e 74 65 78 74 20 2a 2f 0a  tion context */.
6b20: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 76    int (*xOpen)(v
6b30: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c 20 63  oid *pAppData, c
6b40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
6b50: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
6b60: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
6b70: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
6b80: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
6b90: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 76 6f 69  t (*xDelete)(voi
6ba0: 64 20 2a 70 41 70 70 44 61 74 61 2c 20 63 6f 6e  d *pAppData, con
6bb0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
6bc0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
6bd0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 76  int (*xAccess)(v
6be0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c 20 63  oid *pAppData, c
6bf0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
6c00: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
6c10: 69 6e 74 20 28 2a 78 47 65 74 54 65 6d 70 4e 61  int (*xGetTempNa
6c20: 6d 65 29 28 76 6f 69 64 20 2a 70 41 70 70 44 61  me)(void *pAppDa
6c30: 74 61 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ta, char *zOut);
6c40: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
6c50: 74 68 6e 61 6d 65 29 28 76 6f 69 64 20 2a 70 41  thname)(void *pA
6c60: 70 70 44 61 74 61 2c 20 63 6f 6e 73 74 20 63 68  ppData, const ch
6c70: 61 72 20 2a 7a 4e 61 6d 65 2c 20 63 68 61 72 20  ar *zName, char 
6c80: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
6c90: 28 2a 78 44 6c 4f 70 65 6e 29 28 76 6f 69 64 20  (*xDlOpen)(void 
6ca0: 2a 70 41 70 70 44 61 74 61 2c 20 63 6f 6e 73 74  *pAppData, const
6cb0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
6cc0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
6cd0: 72 72 6f 72 29 28 76 6f 69 64 20 2a 70 41 70 70  rror)(void *pApp
6ce0: 44 61 74 61 2c 20 69 6e 74 20 6e 42 79 74 65 2c  Data, int nByte,
6cf0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
6d00: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79  .  void *(*xDlSy
6d10: 6d 29 28 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  m)(void*, const 
6d20: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a  char *zSymbol);.
6d30: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
6d40: 65 29 28 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  e)(void*);.  int
6d50: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
6d60: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c 20  void *pAppData, 
6d70: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
6d80: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
6d90: 78 53 6c 65 65 70 29 28 76 6f 69 64 20 2a 70 41  xSleep)(void *pA
6da0: 70 70 44 61 74 61 2c 20 69 6e 74 20 6d 69 63 72  ppData, int micr
6db0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
6dc0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
6dd0: 28 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c  (void *pAppData,
6de0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20   double*);.  /* 
6df0: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
6e00: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
6e10: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
6e20: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
6e30: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
6e40: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
6e50: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f  this happens. */
6e60: 0a 7d 3b 0a 0a 23 64 65 66 69 6e 65 20 53 51 4c  .};..#define SQL
6e70: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
6e80: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
6e90: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
6ea0: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65  DWRITE 1.#define
6eb0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
6ec0: 45 41 44 4f 4e 4c 59 20 20 32 0a 0a 2f 2a 0a 2a  EADONLY  2../*.*
6ed0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
6ee0: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
6ef0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
6f00: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  des.**.** This r
6f10: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
6f20: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
6f30: 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  * [SQLITE_IOERR_
6f40: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
6f50: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
6f60: 61 74 75 72 65 2e 0a 2a 2a 20 42 79 20 64 65 66  ature..** By def
6f70: 61 75 6c 74 2c 20 53 51 4c 69 74 65 20 41 50 49  ault, SQLite API
6f80: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
6f90: 20 6f 6e 65 20 6f 66 20 6f 6e 6c 79 20 32 36 20   one of only 26 
6fa0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
6fb0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
6fc0: 6f 64 65 73 5d 2e 20 20 57 68 65 6e 20 65 78 74  odes].  When ext
6fd0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
6fe0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
6ff0: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
7000: 65 2c 20 74 68 65 20 72 65 70 65 74 6f 69 72 65  e, the repetoire
7010: 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 64 65 73   of result codes
7020: 20 63 61 6e 20 62 65 0a 2a 2a 20 6d 75 63 68 20   can be.** much 
7030: 6c 61 72 67 65 72 20 61 6e 64 20 63 61 6e 20 28  larger and can (
7040: 68 6f 70 65 66 75 6c 6c 79 29 20 70 72 6f 76 69  hopefully) provi
7050: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
7060: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
7070: 61 62 6f 75 74 20 74 68 65 20 63 61 75 73 65 20  about the cause 
7080: 6f 66 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a  of an error..**.
7090: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
70a0: 67 75 6d 65 6e 74 20 69 73 20 61 20 62 6f 6f 6c  gument is a bool
70b0: 65 61 6e 20 76 61 6c 75 65 20 74 68 61 74 20 74  ean value that t
70c0: 75 72 6e 73 20 65 78 74 65 6e 64 65 64 20 72 65  urns extended re
70d0: 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 6f 6e  sult.** codes on
70e0: 20 61 6e 64 20 6f 66 66 2e 20 20 45 78 74 65 6e   and off.  Exten
70f0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
7100: 20 61 72 65 20 6f 66 66 20 62 79 20 64 65 66 61   are off by defa
7110: 75 6c 74 20 66 6f 72 0a 2a 2a 20 62 61 63 6b 77  ult for.** backw
7120: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
7130: 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 76 65  ty with older ve
7140: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
7150: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
7160: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
7170: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
7180: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
7190: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
71a0: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
71b0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79  **.** Each entry
71c0: 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61   in an SQLite ta
71d0: 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65  ble has a unique
71e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
71f0: 6e 74 65 67 65 72 20 6b 65 79 0a 2a 2a 20 63 61  nteger key.** ca
7200: 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64 22  lled the "rowid"
7210: 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 61  . The rowid is a
7220: 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 20  lways available 
7230: 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
7240: 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  .** column named
7250: 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
7260: 5f 52 4f 57 49 44 5f 2e 20 20 49 66 20 74 68 65  _ROWID_.  If the
7270: 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
7280: 75 6d 6e 20 6f 66 0a 2a 2a 20 74 79 70 65 20 49  umn of.** type I
7290: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
72a0: 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  EY then that col
72b0: 75 6d 6e 20 69 73 20 61 6e 6f 74 68 65 72 20 61  umn is another a
72c0: 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 0a  n alias for the.
72d0: 2a 2a 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  ** rowid..**.** 
72e0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
72f0: 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f  urns the rowid o
7300: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
7310: 74 20 49 4e 53 45 52 54 20 69 6e 74 6f 0a 2a 2a  t INSERT into.**
7320: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
7330: 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20  om the database 
7340: 63 6f 6e 6e 65 63 74 69 6f 6e 20 67 69 76 65 6e  connection given
7350: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a   in the first .*
7360: 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20  * argument.  If 
7370: 6e 6f 20 69 6e 73 65 72 74 73 20 68 61 76 65 20  no inserts have 
7380: 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
7390: 20 74 68 69 73 20 64 61 74 61 62 61 73 65 0a 2a   this database.*
73a0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  * connection, ze
73b0: 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
73c0: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45  **.** If an INSE
73d0: 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  RT occurs within
73e0: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
73f0: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
7400: 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 6f  e.** inserted ro
7410: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
7420: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
7430: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
7440: 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  gger.** is runni
7450: 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 74 68  ng.  But once th
7460: 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e  e trigger termin
7470: 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ates, the value 
7480: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74  returned.** by t
7490: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
74a0: 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20  rts to the last 
74b0: 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62  value inserted b
74c0: 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72 69  efore the.** tri
74d0: 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a  gger fired..**.*
74e0: 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
74f0: 65 61 64 20 64 6f 65 73 20 61 20 6e 65 77 20 69  ead does a new i
7500: 6e 73 65 72 74 20 6f 6e 20 74 68 65 20 73 61 6d  nsert on the sam
7510: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
7520: 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74  ction.** while t
7530: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
7540: 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
7550: 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
7560: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a   insert rowid,.*
7570: 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
7580: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
7590: 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
75a0: 69 6e 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  ined..*/.sqlite3
75b0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
75c0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
75d0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
75e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
75f0: 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
7600: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
7610: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
7620: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
7630: 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
7640: 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
7650: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 28 6f 72 20   changed.** (or 
7660: 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
7670: 74 65 64 29 20 62 79 20 74 68 65 20 6d 6f 73 74  ted) by the most
7680: 20 72 65 63 65 6e 74 20 53 51 4c 20 73 74 61 74   recent SQL stat
7690: 65 6d 65 6e 74 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ement.  Only.** 
76a0: 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
76b0: 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
76c0: 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45 52  ied by the INSER
76d0: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a 2a  T, UPDATE, or.**
76e0: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
76f0: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
7700: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
7710: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
7720: 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20  riggers are not 
7730: 63 6f 75 6e 74 65 64 2e 20 20 55 73 65 20 74 68  counted.  Use th
7740: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
7750: 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
7760: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20  tion.** to find 
7770: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
7780: 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c   of changes incl
7790: 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
77a0: 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
77b0: 2e 0a 2a 2a 0a 2a 2a 20 57 69 74 68 69 6e 20 74  ..**.** Within t
77c0: 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
77d0: 67 67 65 72 2c 20 74 68 65 20 73 71 6c 69 74 65  gger, the sqlite
77e0: 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
77f0: 72 66 61 63 65 20 63 61 6e 20 62 65 0a 2a 2a 20  rface can be.** 
7800: 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
7810: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
7820: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
7830: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
7840: 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
7850: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
7860: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
7870: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
7880: 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a   the trigger..**
7890: 0a 2a 2a 20 41 6c 6c 20 63 68 61 6e 67 65 73 20  .** All changes 
78a0: 61 72 65 20 63 6f 75 6e 74 65 64 2c 20 65 76 65  are counted, eve
78b0: 6e 20 69 66 20 74 68 65 79 20 77 65 72 65 20 6c  n if they were l
78c0: 61 74 65 72 20 75 6e 64 6f 6e 65 20 62 79 20 61  ater undone by a
78d0: 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b 20 6f 72 20  .** ROLLBACK or 
78e0: 41 42 4f 52 54 2e 20 20 45 78 63 65 70 74 2c 20  ABORT.  Except, 
78f0: 63 68 61 6e 67 65 73 20 61 73 73 6f 63 69 61 74  changes associat
7900: 65 64 20 77 69 74 68 20 63 72 65 61 74 69 6e 67  ed with creating
7910: 20 61 6e 64 0a 2a 2a 20 64 72 6f 70 70 69 6e 67   and.** dropping
7920: 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20   tables are not 
7930: 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  counted..**.** I
7940: 66 20 61 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  f a callback inv
7950: 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  okes [sqlite3_ex
7960: 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
7970: 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
7980: 69 76 65 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20 74  ively,.** then t
7990: 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  he changes in th
79a0: 65 20 69 6e 6e 65 72 2c 20 72 65 63 75 72 73 69  e inner, recursi
79b0: 76 65 20 63 61 6c 6c 20 61 72 65 20 63 6f 75 6e  ve call are coun
79c0: 74 65 64 20 74 6f 67 65 74 68 65 72 0a 2a 2a 20  ted together.** 
79d0: 77 69 74 68 20 74 68 65 20 63 68 61 6e 67 65 73  with the changes
79e0: 20 69 6e 20 74 68 65 20 6f 75 74 65 72 20 63 61   in the outer ca
79f0: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ll..**.** SQLite
7a00: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
7a10: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
7a20: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
7a30: 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75  out a WHERE clau
7a40: 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e  se.** by droppin
7a50: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
7a60: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
7a70: 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65  is is much faste
7a80: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20  r than going.** 
7a90: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
7aa0: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
7ab0: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
7ac0: 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75  e table.)  Becau
7ad0: 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70  se of.** this op
7ae0: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
7af0: 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72  change count for
7b00: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
7b10: 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ble" will be.** 
7b20: 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20  zero regardless 
7b30: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
7b40: 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77   elements that w
7b50: 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69  ere originally i
7b60: 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20  n the.** table. 
7b70: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
7b80: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
7b90: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
7ba0: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
7bb0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
7bc0: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
7bd0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  ad..**.** If ano
7be0: 74 68 65 72 20 74 68 72 65 61 64 20 6d 61 6b 65  ther thread make
7bf0: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
7c00: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
7c10: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
7c20: 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
7c30: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
7c40: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
7c50: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
7c60: 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
7c70: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
7c80: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
7c90: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
7ca0: 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
7cb0: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
7cc0: 65 64 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ed.***.** This f
7cd0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
7ce0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
7cf0: 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
7d00: 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 6d 6f   have been.** mo
7d10: 64 69 66 69 65 64 20 62 79 20 49 4e 53 45 52 54  dified by INSERT
7d20: 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
7d30: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  TE statements si
7d40: 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nce the database
7d50: 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f   handle.** was o
7d60: 70 65 6e 65 64 2e 20 54 68 69 73 20 69 6e 63 6c  pened. This incl
7d70: 75 64 65 73 20 55 50 44 41 54 45 2c 20 49 4e 53  udes UPDATE, INS
7d80: 45 52 54 20 61 6e 64 20 44 45 4c 45 54 45 20 73  ERT and DELETE s
7d90: 74 61 74 65 6d 65 6e 74 73 20 65 78 65 63 75 74  tatements execut
7da0: 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ed.** as part of
7db0: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
7dc0: 73 2e 20 41 6c 6c 20 63 68 61 6e 67 65 73 20 61  s. All changes a
7dd0: 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f  re counted as so
7de0: 6f 6e 20 61 73 20 74 68 65 0a 2a 2a 20 73 74 61  on as the.** sta
7df0: 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
7e00: 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
7e10: 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
7e20: 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69  atement handle i
7e30: 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b  s.** passed to [
7e40: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
7e50: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
7e60: 61 6c 69 73 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alise()])..**.**
7e70: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
7e80: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 28 29 5d  qlite3_change()]
7e90: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
7ea0: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
7eb0: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
7ec0: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
7ed0: 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
7ee0: 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
7ef0: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
7f00: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
7f10: 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
7f20: 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ch faster than g
7f30: 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
7f40: 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
7f50: 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
7f60: 20 66 6f 72 6d 20 74 68 65 20 74 61 62 6c 65 2e   form the table.
7f70: 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a  )  Because of.**
7f80: 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69   this optimizati
7f90: 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63  on, the change c
7fa0: 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45  ount for "DELETE
7fb0: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c   FROM table" wil
7fc0: 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67  l be.** zero reg
7fd0: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e  ardless of the n
7fe0: 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74  umber of element
7ff0: 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67  s that were orig
8000: 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a  inally in the.**
8010: 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61   table. To get a
8020: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
8030: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
8040: 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
8050: 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
8060: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
8070: 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a  1" instead..**.*
8080: 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
8090: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
80a0: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
80b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
80c0: 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20  n.** while this 
80d0: 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
80e0: 6e 67 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ng then the retu
80f0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
8100: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75   routine.** is u
8110: 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
8120: 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
8130: 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
8140: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8150: 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
8160: 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
8170: 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  y.**.** This fun
8180: 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
8190: 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
81a0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
81b0: 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
81c0: 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
81d0: 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
81e0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
81f0: 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
8200: 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
8210: 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
8220: 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
8230: 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
8240: 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
8250: 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
8260: 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
8270: 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
8280: 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
8290: 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f  ** It is safe to
82a0: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
82b0: 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
82c0: 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
82d0: 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
82e0: 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
82f0: 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
8300: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
8310: 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
8320: 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
8330: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
8340: 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
8350: 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20 69  ection that.** i
8360: 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
8370: 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
8380: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
8390: 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
83a0: 2a 20 54 68 65 20 53 51 4c 20 6f 70 65 72 61 74  * The SQL operat
83b0: 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
83c0: 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
83d0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
83e0: 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 61 6e  RRUPT]..** If an
83f0: 20 69 6e 74 65 72 72 75 70 74 65 64 20 6f 70 65   interrupted ope
8400: 72 61 74 69 6f 6e 20 77 61 73 20 61 6e 20 75 70  ration was an up
8410: 64 61 74 65 20 74 68 61 74 20 69 73 20 69 6e 73  date that is ins
8420: 69 64 65 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  ide an.** explic
8430: 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
8440: 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
8450: 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c 6c  transaction will
8460: 20 62 65 20 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61   be rolled.** ba
8470: 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
8480: 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
8490: 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
84a0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
84b0: 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
84c0: 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
84d0: 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
84e0: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  e.**.** These fu
84f0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 74  nctions return t
8500: 72 75 65 20 69 66 20 74 68 65 20 67 69 76 65 6e  rue if the given
8510: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 63 6f   input string co
8520: 6d 70 72 69 73 65 73 0a 2a 2a 20 6f 6e 65 20 6f  mprises.** one o
8530: 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 74 65 20  r more complete 
8540: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
8550: 46 6f 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  For the sqlite3_
8560: 63 6f 6d 70 6c 65 74 65 28 29 20 63 61 6c 6c 2c  complete() call,
8570: 0a 2a 2a 20 74 68 65 20 70 61 72 61 6d 65 74 65  .** the paramete
8580: 72 20 6d 75 73 74 20 62 65 20 61 20 6e 75 6c 2d  r must be a nul-
8590: 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
85a0: 20 73 74 72 69 6e 67 2e 20 46 6f 72 0a 2a 2a 20   string. For.** 
85b0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
85c0: 31 36 28 29 2c 20 61 20 6e 75 6c 2d 74 65 72 6d  16(), a nul-term
85d0: 69 6e 61 74 65 64 20 6d 61 63 68 69 6e 65 20 62  inated machine b
85e0: 79 74 65 20 6f 72 64 65 72 20 55 54 46 2d 31 36  yte order UTF-16
85f0: 20 73 74 72 69 6e 67 0a 2a 2a 20 69 73 20 72 65   string.** is re
8600: 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
8610: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
8620: 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d   useful for comm
8630: 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
8640: 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
8650: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
8660: 65 6e 74 65 72 65 64 20 74 65 78 74 20 66 6f 72  entered text for
8670: 6d 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ms one or more c
8680: 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
8690: 65 6d 65 6e 74 73 20 6f 72 0a 2a 2a 20 69 66 20  ements or.** if 
86a0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
86b0: 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
86c0: 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 73 74  e sending the st
86d0: 61 74 65 6d 65 6e 74 73 20 69 6e 74 6f 0a 2a 2a  atements into.**
86e0: 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
86f0: 69 6e 67 2e 20 54 68 65 20 61 6c 67 6f 72 69 74  ing. The algorit
8700: 68 6d 20 69 73 20 73 69 6d 70 6c 65 2e 20 20 49  hm is simple.  I
8710: 66 20 74 68 65 20 0a 2a 2a 20 6c 61 73 74 20 74  f the .** last t
8720: 6f 6b 65 6e 20 6f 74 68 65 72 20 74 68 61 6e 20  oken other than 
8730: 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6d 6d 65  spaces and comme
8740: 6e 74 73 20 69 73 20 61 20 73 65 6d 69 63 6f 6c  nts is a semicol
8750: 6f 6e 2c 20 74 68 65 6e 20 72 65 74 75 72 6e 20  on, then return 
8760: 0a 2a 2a 20 74 72 75 65 2e 20 20 41 63 74 75 61  .** true.  Actua
8770: 6c 6c 79 2c 20 74 68 65 20 61 6c 67 6f 72 69 74  lly, the algorit
8780: 68 6d 20 69 73 20 61 20 6c 69 74 74 6c 65 20 6d  hm is a little m
8790: 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20  ore complicated 
87a0: 74 68 61 6e 20 74 68 61 74 0a 2a 2a 20 69 6e 20  than that.** in 
87b0: 6f 72 64 65 72 20 74 6f 20 64 65 61 6c 20 77 69  order to deal wi
87c0: 74 68 20 74 72 69 67 67 65 72 73 2c 20 62 75 74  th triggers, but
87d0: 20 74 68 65 20 62 61 73 69 63 20 69 64 65 61 20   the basic idea 
87e0: 69 73 20 74 68 65 20 73 61 6d 65 3a 20 20 74 68  is the same:  th
87f0: 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  e.** statement i
8800: 73 20 6e 6f 74 20 63 6f 6d 70 6c 65 74 65 20 75  s not complete u
8810: 6e 6c 65 73 73 20 69 74 20 65 6e 64 73 20 69 6e  nless it ends in
8820: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2e 0a 2a 2f   a semicolon..*/
8830: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
8840: 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
8850: 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
8860: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
8870: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
8880: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
8890: 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
88a0: 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
88b0: 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
88c0: 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  rs.**.** This ro
88d0: 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65 73  utine identifies
88e0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
88f0: 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
8900: 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
8910: 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d 70  enever an attemp
8920: 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
8930: 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
8940: 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f 74  le .** that anot
8950: 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70 72  her thread or pr
8960: 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
8970: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79  ..** If the busy
8980: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
8990: 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
89a0: 42 55 53 59 5d 0a 2a 2a 20 28 6f 72 20 73 6f 6d  BUSY].** (or som
89b0: 65 74 69 6d 65 73 20 5b 53 51 4c 49 54 45 5f 49  etimes [SQLITE_I
89c0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 29 0a 2a  OERR_BLOCKED]).*
89d0: 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
89e0: 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
89f0: 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
8a00: 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20  lock..** If the 
8a10: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
8a20: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
8a30: 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  the.** callback 
8a40: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
8a50: 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
8a60: 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69 72 73  ts.  The.** firs
8a70: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
8a80: 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  e handler is a c
8a90: 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
8aa0: 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
8ab0: 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
8ac0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
8ad0: 72 6f 75 74 69 6e 65 2e 20 20 54 68 65 20 73 65  routine.  The se
8ae0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
8af0: 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
8b00: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
8b10: 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
8b20: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
8b30: 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
8b40: 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
8b50: 67 20 65 76 65 6e 74 2e 20 49 66 20 74 68 65 0a  g event. If the.
8b60: 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
8b70: 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
8b80: 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
8b90: 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
8ba0: 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
8bb0: 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
8bc0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
8bd0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
8be0: 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
8bf0: 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
8c00: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
8c10: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
8c20: 6f 74 68 65 72 20 61 74 74 65 6d 70 74 20 69 73  other attempt is
8c30: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
8c40: 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 6f  e.** database fo
8c50: 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
8c60: 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
8c70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
8c80: 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
8c90: 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
8ca0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 0a 2a 2a  uarantee that.**
8cb0: 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
8cc0: 6b 65 64 20 77 68 65 6e 20 74 68 65 72 65 20 69  ked when there i
8cd0: 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
8ce0: 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20  n..** If SQLite 
8cf0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
8d00: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
8d10: 79 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  y handler could 
8d20: 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64  result in.** a d
8d30: 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
8d40: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
8d50: 42 55 53 59 5d 20 69 6e 73 74 65 61 64 2e 0a 2a  BUSY] instead..*
8d60: 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
8d70: 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
8d80: 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
8d90: 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
8da0: 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
8db0: 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
8dc0: 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
8dd0: 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
8de0: 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
8df0: 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
8e00: 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
8e10: 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
8e20: 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
8e30: 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
8e40: 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
8e50: 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
8e60: 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
8e70: 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
8e80: 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
8e90: 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
8ea0: 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
8eb0: 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
8ec0: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
8ed0: 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
8ee0: 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
8ef0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
8f00: 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
8f10: 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
8f20: 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
8f30: 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
8f40: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
8f50: 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
8f60: 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
8f70: 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
8f80: 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
8f90: 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
8fa0: 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
8fb0: 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
8fc0: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
8fd0: 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
8fe0: 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73   The default bus
8ff0: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
9000: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  LL..**.** The [S
9010: 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
9020: 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
9030: 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
9040: 42 4c 4f 43 4b 45 44 5d 20 77 68 65 6e 0a 2a 2a  BLOCKED] when.**
9050: 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
9060: 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
9070: 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
9080: 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
9090: 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
90a0: 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
90b0: 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
90c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
90d0: 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
90e0: 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
90f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9100: 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
9110: 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
9120: 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
9130: 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
9140: 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
9150: 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
9160: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9170: 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
9180: 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
9190: 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73  aders.  If it is
91a0: 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
91b0: 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
91c0: 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
91d0: 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
91e0: 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
91f0: 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
9200: 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
9210: 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
9220: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
9230: 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
9240: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
9250: 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
9260: 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
9270: 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73  _BLOCKED].  This
9280: 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
9290: 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
92a0: 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
92b0: 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
92c0: 6e 67 65 73 2e 20 53 65 65 20 74 68 65 0a 2a 2a  nges. See the.**
92d0: 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f   <a href="http:/
92e0: 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f  /www.sqlite.org/
92f0: 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
9300: 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
9310: 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
9320: 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
9330: 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
9340: 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
9350: 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
9360: 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
9370: 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a  mportant..**..**
9380: 20 53 71 6c 69 74 65 20 69 73 20 72 65 2d 65 6e   Sqlite is re-en
9390: 74 72 61 6e 74 2c 20 73 6f 20 74 68 65 20 62 75  trant, so the bu
93a0: 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 73  sy handler may s
93b0: 74 61 72 74 20 61 20 6e 65 77 20 71 75 65 72 79  tart a new query
93c0: 2e 20 0a 2a 2a 20 28 49 74 20 69 73 20 6e 6f 74  . .** (It is not
93d0: 20 63 6c 65 61 72 20 77 68 79 20 61 6e 79 6f 6e   clear why anyon
93e0: 65 20 77 6f 75 6c 64 20 65 76 65 72 79 20 77 61  e would every wa
93f0: 6e 74 20 74 6f 20 64 6f 20 74 68 69 73 2c 20 62  nt to do this, b
9400: 75 74 20 69 74 0a 2a 2a 20 69 73 20 61 6c 6c 6f  ut it.** is allo
9410: 77 65 64 2c 20 69 6e 20 74 68 65 6f 72 79 2e 29  wed, in theory.)
9420: 20 20 42 75 74 20 74 68 65 20 62 75 73 79 20 68    But the busy h
9430: 61 6e 64 6c 65 72 20 6d 61 79 20 6e 6f 74 20 63  andler may not c
9440: 6c 6f 73 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  lose the.** data
9450: 62 61 73 65 2e 20 20 43 6c 6f 73 69 6e 67 20 74  base.  Closing t
9460: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
9470: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
9480: 77 69 6c 6c 20 64 65 6c 65 74 65 20 0a 2a 2a 20  will delete .** 
9490: 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
94a0: 6f 75 74 20 66 72 6f 6d 20 75 6e 64 65 72 20 74  out from under t
94b0: 68 65 20 65 78 65 63 75 74 69 6e 67 20 71 75 65  he executing que
94c0: 72 79 20 61 6e 64 20 77 69 6c 6c 20 0a 2a 2a 20  ry and will .** 
94d0: 70 72 6f 62 61 62 6c 79 20 72 65 73 75 6c 74 20  probably result 
94e0: 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
94f0: 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
9500: 20 72 75 6e 74 69 6d 65 20 65 72 72 6f 72 2e 0a   runtime error..
9510: 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
9520: 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
9530: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
9540: 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 20 64  fined for each d
9550: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
9560: 63 74 69 6f 6e 2e 20 20 53 65 74 74 69 6e 67 20  ction.  Setting 
9570: 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
9580: 65 72 20 63 6c 65 61 72 73 20 61 6e 79 20 70 72  er clears any pr
9590: 65 76 69 6f 75 73 20 6f 6e 65 2e 0a 2a 2a 20 4e  evious one..** N
95a0: 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
95b0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
95c0: 69 6d 65 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61  imeout()] will a
95d0: 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
95e0: 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
95f0: 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  dler..**.** When
9600: 20 6f 70 65 72 61 74 69 6e 67 20 69 6e 20 5b 73   operating in [s
9610: 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
9620: 61 72 65 64 5f 63 61 63 68 65 20 7c 20 73 68 61  ared_cache | sha
9630: 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
9640: 0a 2a 2a 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c  .** only a singl
9650: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
9660: 61 6e 20 62 65 20 64 65 66 69 6e 65 64 20 66 6f  an be defined fo
9670: 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  r each database 
9680: 66 69 6c 65 2e 0a 2a 2a 20 53 6f 20 69 66 20 74  file..** So if t
9690: 77 6f 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  wo database conn
96a0: 65 63 74 69 6f 6e 73 20 73 68 61 72 65 20 61 20  ections share a 
96b0: 73 69 6e 67 6c 65 20 63 61 63 68 65 2c 20 74 68  single cache, th
96c0: 65 6e 20 63 68 61 6e 67 69 6e 67 0a 2a 2a 20 74  en changing.** t
96d0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
96e0: 6f 6e 20 6f 6e 65 20 63 6f 6e 6e 65 63 74 69 6f  on one connectio
96f0: 6e 20 77 69 6c 6c 20 61 6c 73 6f 20 63 68 61 6e  n will also chan
9700: 67 65 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ge the busy.** h
9710: 61 6e 64 6c 65 72 20 69 6e 20 74 68 65 20 6f 74  andler in the ot
9720: 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  her connection. 
9730: 20 54 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   The busy handle
9740: 72 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  r is invoked.** 
9750: 69 6e 20 74 68 65 20 74 68 72 65 61 64 20 74 68  in the thread th
9760: 61 74 20 77 61 73 20 72 75 6e 6e 69 6e 67 20 77  at was running w
9770: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 42  hen the SQLITE_B
9780: 55 53 59 20 77 61 73 20 68 69 74 2e 0a 2a 2f 0a  USY was hit..*/.
9790: 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
97a0: 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
97b0: 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
97c0: 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
97d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
97e0: 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
97f0: 74 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  t.**.** This rou
9800: 74 69 6e 65 20 73 65 74 73 20 61 20 62 75 73 79  tine sets a busy
9810: 20 68 61 6e 64 6c 65 72 20 74 68 61 74 20 73 6c   handler that sl
9820: 65 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65  eeps for a while
9830: 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65   when a.** table
9840: 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65   is locked.  The
9850: 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c   handler will sl
9860: 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
9870: 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20  es until .** at 
9880: 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
9890: 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
98a0: 69 6e 67 20 68 61 76 65 20 62 65 65 6e 20 64 6f  ing have been do
98b0: 6e 65 2e 20 20 41 66 74 65 72 0a 2a 2a 20 22 6d  ne.  After.** "m
98c0: 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
98d0: 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68 65  of sleeping, the
98e0: 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
98f0: 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75 73   0 which.** caus
9900: 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
9910: 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b 53  ()] to return [S
9920: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
9930: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
9940: 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  CKED]..**.** Cal
9950: 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
9960: 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
9970: 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
9980: 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
9990: 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
99a0: 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
99b0: 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
99c0: 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
99d0: 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
99e0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
99f0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9a00: 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ion.  If another
9a10: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 61   busy handler wa
9a20: 73 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20 28  s defined  .** (
9a30: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
9a40: 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
9a50: 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
9a60: 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
9a70: 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
9a80: 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
9a90: 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ared..*/.int sql
9aa0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
9ab0: 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
9ac0: 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
9ad0: 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
9ae0: 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
9af0: 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
9b00: 2a 0a 2a 2a 20 54 68 69 73 20 6e 65 78 74 20 72  *.** This next r
9b10: 6f 75 74 69 6e 65 20 69 73 20 61 20 63 6f 6e 76  outine is a conv
9b20: 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20  enience wrapper 
9b30: 61 72 6f 75 6e 64 20 5b 73 71 6c 69 74 65 33 5f  around [sqlite3_
9b40: 65 78 65 63 28 29 5d 2e 0a 2a 2a 20 49 6e 73 74  exec()]..** Inst
9b50: 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
9b60: 61 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20  a user-supplied 
9b70: 63 61 6c 6c 62 61 63 6b 20 66 6f 72 20 65 61 63  callback for eac
9b80: 68 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20  h row of the.** 
9b90: 72 65 73 75 6c 74 2c 20 74 68 69 73 20 72 6f 75  result, this rou
9ba0: 74 69 6e 65 20 72 65 6d 65 6d 62 65 72 73 20 65  tine remembers e
9bb0: 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ach row of the r
9bc0: 65 73 75 6c 74 20 69 6e 20 6d 65 6d 6f 72 79 0a  esult in memory.
9bd0: 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
9be0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
9bf0: 28 29 5d 2c 20 74 68 65 6e 20 72 65 74 75 72 6e  ()], then return
9c00: 73 20 61 6c 6c 20 6f 66 20 74 68 65 20 72 65 73  s all of the res
9c10: 75 6c 74 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  ult after the.**
9c20: 20 71 75 65 72 79 20 68 61 73 20 66 69 6e 69 73   query has finis
9c30: 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 41 73 20 61  hed. .**.** As a
9c40: 6e 20 65 78 61 6d 70 6c 65 2c 20 73 75 70 70 6f  n example, suppo
9c50: 73 65 20 74 68 65 20 71 75 65 72 79 20 72 65 73  se the query res
9c60: 75 6c 74 20 77 68 65 72 65 20 74 68 69 73 20 74  ult where this t
9c70: 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  able:.**.** <pre
9c80: 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
9c90: 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
9ca0: 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
9cb0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
9cc0: 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
9cd0: 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
9ce0: 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
9cf0: 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
9d00: 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
9d10: 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
9d20: 20 49 66 20 74 68 65 20 33 72 64 20 61 72 67 75   If the 3rd argu
9d30: 6d 65 6e 74 20 77 65 72 65 20 26 61 7a 52 65 73  ment were &azRes
9d40: 75 6c 74 20 74 68 65 6e 20 61 66 74 65 72 20 74  ult then after t
9d50: 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
9d60: 72 6e 73 0a 2a 2a 20 61 7a 52 65 73 75 6c 74 20  rns.** azResult 
9d70: 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65  will contain the
9d80: 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 61 74 61 3a   following data:
9d90: 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
9da0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b         azResult[
9db0: 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
9dc0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b         azResult[
9dd0: 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
9de0: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 32        azResult[2
9df0: 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
9e00: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b         azResult[
9e10: 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
9e20: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 34 5d       azResult[4]
9e30: 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
9e40: 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 35 5d 20      azResult[5] 
9e50: 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
9e60: 20 20 61 7a 52 65 73 75 6c 74 5b 36 5d 20 3d 20    azResult[6] = 
9e70: 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
9e80: 20 20 20 61 7a 52 65 73 75 6c 74 5b 37 5d 20 3d     azResult[7] =
9e90: 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
9ea0: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 69 63 65 20 74 68  .**.** Notice th
9eb0: 61 74 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  at there is an e
9ec0: 78 74 72 61 20 72 6f 77 20 6f 66 20 64 61 74 61  xtra row of data
9ed0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9ee0: 63 6f 6c 75 6d 6e 0a 2a 2a 20 68 65 61 64 65 72  column.** header
9ef0: 73 2e 20 20 42 75 74 20 74 68 65 20 2a 6e 72 6f  s.  But the *nro
9f00: 77 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  w return value i
9f10: 73 20 73 74 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f  s still 3.  *nco
9f20: 6c 75 6d 6e 20 69 73 0a 2a 2a 20 73 65 74 20 74  lumn is.** set t
9f30: 6f 20 32 2e 20 20 49 6e 20 67 65 6e 65 72 61 6c  o 2.  In general
9f40: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  , the number of 
9f50: 76 61 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20  values inserted 
9f60: 69 6e 74 6f 20 61 7a 52 65 73 75 6c 74 0a 2a 2a  into azResult.**
9f70: 20 77 69 6c 6c 20 62 65 20 28 28 2a 6e 72 6f 77   will be ((*nrow
9f80: 29 20 2b 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e  ) + 1)*(*ncolumn
9f90: 29 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  )..**.** After t
9fa0: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
9fb0: 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
9fc0: 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c   using the resul
9fd0: 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  t, it should .**
9fe0: 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
9ff0: 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f   data pointer to
a000: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
a010: 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
a020: 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  o .** release th
a030: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
a040: 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65  s malloc-ed.  Be
a050: 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
a060: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
a070: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
a080: 65 6e 73 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  ens, the calling
a090: 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
a0a0: 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 0a  ot try to call .
a0b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
a0c0: 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
a0d0: 6e 6c 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  nly [sqlite3_fre
a0e0: 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
a0f0: 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 0a 2a  le to release .*
a100: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  * the memory pro
a110: 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
a120: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75  ..**.** The retu
a130: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
a140: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
a150: 73 61 6d 65 20 61 73 20 66 72 6f 6d 20 5b 73 71  same as from [sq
a160: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a  lite3_exec()]..*
a170: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
a180: 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
a190: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
a1a0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
a1b0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
a1c0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
a1d0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
a1e0: 78 65 63 75 74 65 64 20 2a 2f 0a 20 20 63 68 61  xecuted */.  cha
a1f0: 72 20 2a 2a 2a 72 65 73 75 6c 74 70 2c 20 20 20  r ***resultp,   
a200: 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 20 77 72      /* Result wr
a210: 69 74 74 65 6e 20 74 6f 20 61 20 63 68 61 72 20  itten to a char 
a220: 2a 5b 5d 20 20 74 68 61 74 20 74 68 69 73 20 70  *[]  that this p
a230: 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a 20 20 69 6e  oints to */.  in
a240: 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20  t *nrow,        
a250: 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
a260: 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
a270: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
a280: 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20  int *ncolumn,   
a290: 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
a2a0: 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
a2b0: 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
a2c0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
a2d0: 73 67 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45  sg          /* E
a2e0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
a2f0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
a300: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
a310: 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
a320: 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
a330: 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
a340: 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
a350: 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
a360: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
a370: 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20  e workalikes of 
a380: 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
a390: 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
a3a0: 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
a3b0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
a3c0: 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
a3d0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
a3e0: 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
a3f0: 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
a400: 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
a410: 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
a420: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
a430: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a440: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
a450: 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
a460: 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
a470: 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
a480: 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
a490: 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f  te3_free()].  Bo
a4a0: 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
a4b0: 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
a4c0: 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
a4d0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
a4e0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
a4f0: 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
a500: 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
a510: 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
a520: 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33  **.** In sqlite3
a530: 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
a540: 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
a550: 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
a560: 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
a570: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
a580: 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
a590: 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
a5a0: 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
a5b0: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
a5c0: 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
a5d0: 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
a5e0: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
a5f0: 72 61 6d 65 74 65 72 2e 20 20 4e 6f 74 65 20 74  rameter.  Note t
a600: 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
a610: 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
a620: 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
a630: 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
a640: 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20  printf().  This 
a650: 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
a660: 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
a670: 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
a680: 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
a690: 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
a6a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
a6b0: 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
a6c0: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
a6d0: 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
a6e0: 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
a6f0: 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
a700: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
a710: 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
a720: 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
a730: 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57  o the buffer.  W
a740: 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
a750: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
a760: 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
a770: 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
a780: 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
a790: 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
a7a0: 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
a7b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a7c0: 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
a7d0: 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
a7e0: 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
a7f0: 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
a800: 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  ** As long as th
a810: 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
a820: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
a830: 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
a840: 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
a850: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
a860: 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
a870: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
a880: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   The first.** pa
a890: 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
a8a0: 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
a8b0: 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
a8c0: 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
a8d0: 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
a8e0: 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
a8f0: 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
a900: 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
a910: 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
a920: 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
a930: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
a940: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
a950: 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
a960: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
a970: 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
a980: 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
a990: 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
a9a0: 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
a9b0: 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
a9c0: 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 20 66  e usual printf f
a9d0: 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
a9e0: 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
a9f0: 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
aa00: 69 73 20 61 72 65 20 22 25 71 22 20 61 6e 64 20  is are "%q" and 
aa10: 22 25 51 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%Q" options..**
aa20: 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
aa30: 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
aa40: 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
aa50: 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
aa60: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
aa70: 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
aa80: 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
aa90: 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
aaa0: 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
aab0: 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
aac0: 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
aad0: 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
aae0: 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
aaf0: 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
ab00: 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
ab10: 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
ab20: 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
ab30: 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
ab40: 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
ab50: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
ab60: 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f  r example, so so
ab70: 6d 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  me string variab
ab80: 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  le contains text
ab90: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
aba0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
abb0: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
abc0: 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
abd0: 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
abe0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
abf0: 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
ac00: 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
ac10: 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
ac20: 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
ac30: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
ac40: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
ac50: 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
ac60: 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
ac70: 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
ac80: 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
ac90: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
aca0: 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
acb0: 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
acc0: 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
acd0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
ace0: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
acf0: 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
ad00: 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
ad10: 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
ad20: 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
ad30: 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
ad40: 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
ad50: 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
ad60: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
ad70: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
ad80: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
ad90: 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
ada0: 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
adb0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
adc0: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
add0: 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
ade0: 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
adf0: 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
ae00: 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
ae10: 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
ae20: 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
ae30: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
ae40: 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
ae50: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
ae60: 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
ae70: 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
ae80: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
ae90: 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
aea0: 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
aeb0: 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
aec0: 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
aed0: 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c  ule you.** shoul
aee0: 64 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  d always use %q 
aef0: 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
af00: 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
af10: 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
af20: 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  .** literal..**.
af30: 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e  ** The %Q option
af40: 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
af50: 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
af60: 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
af70: 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
af80: 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
af90: 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72 20  tal string.  Or 
afa0: 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
afb0: 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74   in the argument
afc0: 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61 20 4e 55  .** list is a NU
afd0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
afe0: 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
aff0: 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
b000: 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75  out single.** qu
b010: 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
b020: 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
b030: 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
b040: 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
b050: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
b060: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
b070: 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
b080: 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
b090: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
b0a0: 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
b0b0: 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
b0c0: 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
b0d0: 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
b0e0: 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
b0f0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
b100: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
b110: 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
b120: 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
b130: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
b140: 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
b150: 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
b160: 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
b170: 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
b180: 6e 74 65 72 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73  nter..*/.char *s
b190: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
b1a0: 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
b1b0: 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
b1c0: 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
b1d0: 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
b1e0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
b1f0: 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
b200: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
b210: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
b220: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
b230: 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
b240: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
b250: 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
b260: 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
b270: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
b280: 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
b290: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b2a0: 20 6e 65 65 64 73 2e 20 20 54 68 65 20 64 65 66   needs.  The def
b2b0: 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ault implementat
b2c0: 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65  ion.** of the me
b2d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b2e0: 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 20 74  subsystem uses t
b2f0: 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  he malloc(), rea
b300: 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72  lloc().** and fr
b310: 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79  ee() provided by
b320: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
b330: 6c 69 62 72 61 72 79 2e 20 20 48 6f 77 65 76 65  library.  Howeve
b340: 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65  r, if .** SQLite
b350: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b360: 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  h the following 
b370: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
b380: 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  acro.**.** <bloc
b390: 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4f  kquote> SQLITE_O
b3a0: 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
b3b0: 41 54 49 4f 4e 20 3c 2f 62 6c 6f 63 6b 71 75 6f  ATION </blockquo
b3c0: 74 65 3e 0a 2a 2a 0a 2a 2a 20 74 68 65 6e 20 6e  te>.**.** then n
b3d0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  o implementation
b3e0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
b3f0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
b400: 62 79 0a 2a 2a 20 53 51 4c 69 74 65 2e 20 20 54  by.** SQLite.  T
b410: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
b420: 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
b430: 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 65  t SQLite is.** e
b440: 78 70 65 63 74 65 64 20 74 6f 20 70 72 6f 76 69  xpected to provi
b450: 64 65 20 69 74 73 20 6f 77 6e 20 69 6d 70 6c 65  de its own imple
b460: 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2f 0a 76 6f  mentation..*/.vo
b470: 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
b480: 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
b490: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
b4a0: 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
b4b0: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
b4c0: 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
b4d0: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
b4e0: 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
b4f0: 63 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64 64 69  cs.**.** In addi
b500: 74 69 6f 6e 20 74 6f 20 74 68 65 20 62 61 73 69  tion to the basi
b510: 63 20 74 68 72 65 65 20 61 6c 6c 6f 63 61 74 69  c three allocati
b520: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20  on routines .** 
b530: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
b540: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
b550: 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
b560: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  e3_realloc()],.*
b570: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
b580: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
b590: 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20  m included with 
b5a0: 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 73 6f  the SQLite.** so
b5b0: 75 72 63 65 73 20 70 72 6f 76 69 64 65 73 20 74  urces provides t
b5c0: 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 68  he interfaces sh
b5d0: 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 0a 2a 2a  own below..**.**
b5e0: 20 54 68 65 20 66 69 72 73 74 20 6f 66 20 74 68   The first of th
b5f0: 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
b600: 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 6d 6f   returns the amo
b610: 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 0a 2a  unt of memory .*
b620: 2a 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  * currently outs
b630: 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
b640: 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
b650: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  .  The second.**
b660: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 61 72   returns the lar
b670: 67 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f  gest instantaneo
b680: 75 73 20 61 6d 6f 75 6e 74 20 6f 66 20 6f 75 74  us amount of out
b690: 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 6d 65 6d 6f  standing.** memo
b6a0: 72 79 2e 20 20 54 68 65 20 68 69 67 68 77 61 74  ry.  The highwat
b6b0: 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
b6c0: 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
b6d0: 20 69 73 0a 2a 2a 20 74 72 75 65 2e 20 20 54 68   is.** true.  Th
b6e0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 64 6f  e SQLite core do
b6f0: 65 73 20 6e 6f 74 20 75 73 65 20 65 69 74 68 65  es not use eithe
b700: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
b710: 6e 65 73 0a 2a 2a 20 61 6e 64 20 73 6f 20 74 68  nes.** and so th
b720: 65 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 74  ey do not have t
b730: 6f 20 62 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64  o be implemented
b740: 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
b750: 69 6f 6e 0a 2a 2a 20 69 66 20 53 51 4c 49 54 45  ion.** if SQLITE
b760: 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
b770: 4f 43 41 54 49 4f 4e 20 69 73 20 64 65 66 69 6e  OCATION is defin
b780: 65 64 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ed.  These routi
b790: 6e 65 73 0a 2a 2a 20 61 72 65 20 70 72 6f 76 69  nes.** are provi
b7a0: 64 65 64 20 62 79 20 74 68 65 20 64 65 66 61 75  ded by the defau
b7b0: 6c 74 20 6d 65 6d 6f 72 79 20 73 75 62 73 79 73  lt memory subsys
b7c0: 74 65 6d 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  tem for diagnost
b7d0: 69 63 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e 0a  ic.** purposes..
b7e0: 2a 2f 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  */.sqlite3_uint6
b7f0: 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
b800: 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
b810: 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69  ite3_uint64 sqli
b820: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
b830: 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
b840: 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
b850: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
b860: 6f 63 61 74 69 6f 6e 20 41 6c 61 72 6d 73 0a 2a  ocation Alarms.*
b870: 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
b880: 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 5d 20  3_memory_alarm] 
b890: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20  routine is used 
b8a0: 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 61  to register.** a
b8b0: 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 6d 65 6d   callback on mem
b8c0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
b8d0: 76 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  vents..**.** Thi
b8e0: 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
b8f0: 65 72 73 20 6f 72 20 63 6c 65 61 72 73 20 61 20  ers or clears a 
b900: 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 66  callbacks that f
b910: 69 72 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65  ires when.** the
b920: 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
b930: 79 20 61 6c 6c 6f 63 61 74 65 64 20 65 78 63 65  y allocated exce
b940: 65 64 73 20 69 54 68 72 65 73 68 6f 6c 64 2e 20  eds iThreshold. 
b950: 20 4f 6e 6c 79 0a 2a 2a 20 61 20 73 69 6e 67 6c   Only.** a singl
b960: 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 62  e callback can b
b970: 65 20 72 65 67 69 73 74 65 72 65 64 20 61 74 20  e registered at 
b980: 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
b990: 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
b9a0: 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29  3_memory_alarm()
b9b0: 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  ] overwrites the
b9c0: 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 62 61   previous callba
b9d0: 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  ck..** The callb
b9e0: 61 63 6b 20 69 73 20 64 69 73 61 62 6c 65 64 20  ack is disabled 
b9f0: 62 79 20 73 65 74 74 69 6e 67 20 78 43 61 6c 6c  by setting xCall
ba00: 62 61 63 6b 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  back to a NULL.*
ba10: 2a 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a  * pointer..** .*
ba20: 2a 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 73  * The parameters
ba30: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
ba40: 20 61 72 65 20 74 68 65 20 70 41 72 67 20 76 61   are the pArg va
ba50: 6c 75 65 2c 20 74 68 65 20 0a 2a 2a 20 61 6d 6f  lue, the .** amo
ba60: 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  unt of memory cu
ba70: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2c 20  rrently in use, 
ba80: 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  and the size of 
ba90: 74 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  the.** allocatio
baa0: 6e 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20  n that provoked 
bab0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  the callback.  T
bac0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c  he callback will
bad0: 0a 2a 2a 20 70 72 65 73 75 6d 61 62 6c 79 20 69  .** presumably i
bae0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
baf0: 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 20 75  ree()] to free u
bb00: 70 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 2e 0a  p memory space..
bb10: 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
bb20: 6d 61 79 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  may invoke [sqli
bb30: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
bb40: 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
bb50: 63 28 29 5d 0a 2a 2a 20 62 75 74 20 69 66 20 69  c()].** but if i
bb60: 74 20 64 6f 65 73 2c 20 6e 6f 20 61 64 64 69 74  t does, no addit
bb70: 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  ional callbacks 
bb80: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
bb90: 62 79 0a 2a 2a 20 74 68 65 20 72 65 63 75 72 73  by.** the recurs
bba0: 69 76 65 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a  ive calls..**.**
bbb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   The [sqlite3_so
bbc0: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d  ft_heap_limit()]
bbd0: 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
bbe0: 20 62 79 20 72 65 67 69 73 74 65 72 69 6e 67 0a   by registering.
bbf0: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 61 72  ** a memory alar
bc00: 6d 20 61 74 20 74 68 65 20 73 6f 66 74 20 68 65  m at the soft he
bc10: 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 69 6e 76  ap limit and inv
bc20: 6f 6b 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  oking .** [sqlit
bc30: 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
bc40: 79 28 29 5d 20 69 6e 20 74 68 65 20 61 6c 61 72  y()] in the alar
bc50: 6d 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 70 70  m callback.  App
bc60: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 6f 67  lication.** prog
bc70: 72 61 6d 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  rams should not 
bc80: 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
bc90: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
bca0: 72 79 5f 61 6c 61 72 6d 28 29 5d 0a 2a 2a 20 69  ry_alarm()].** i
bcb0: 6e 74 65 72 66 61 63 65 20 62 65 63 61 75 73 65  nterface because
bcc0: 20 64 6f 69 6e 67 20 73 6f 20 77 69 6c 6c 20 69   doing so will i
bcd0: 6e 74 65 72 66 65 72 65 20 77 69 74 68 20 74 68  nterfere with th
bce0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f  e.** [sqlite3_so
bcf0: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d  ft_heap_limit()]
bd00: 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e 74 20   module..*/.int 
bd10: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
bd20: 6c 61 72 6d 28 0a 20 20 76 6f 69 64 28 2a 78 43  larm(.  void(*xC
bd30: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 20 2a 70  allback)(void *p
bd40: 41 72 67 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  Arg, sqlite3_uin
bd50: 74 36 34 20 75 73 65 64 2c 20 75 6e 73 69 67 6e  t64 used, unsign
bd60: 65 64 20 69 6e 74 20 4e 29 2c 0a 20 20 76 6f 69  ed int N),.  voi
bd70: 64 20 2a 70 41 72 67 2c 0a 20 20 73 71 6c 69 74  d *pArg,.  sqlit
bd80: 65 33 5f 75 69 6e 74 36 34 20 69 54 68 72 65 73  e3_uint64 iThres
bd90: 68 6f 6c 64 0a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  hold.);.../*.** 
bda0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
bdb0: 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
bdc0: 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
bdd0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
bde0: 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61  ne registers a a
bdf0: 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
be00: 63 6b 20 77 69 74 68 20 74 68 65 20 53 51 4c 69  ck with the SQLi
be10: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 0a 2a 2a  te library.  .**
be20: 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
be30: 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
be40: 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
be50: 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
be60: 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
be70: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
be80: 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
be90: 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
bea0: 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
beb0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
bec0: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
bed0: 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
bee0: 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a  .  At various.**
bef0: 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
bf00: 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
bf10: 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
bf20: 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
bf30: 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
bf40: 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
bf50: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
bf60: 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
bf70: 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
bf80: 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
bf90: 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65  re allowed.  The
bfa0: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
bfb0: 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
bfc0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
bfd0: 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
bfe0: 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
bff0: 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
c000: 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
c010: 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
c020: 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
c030: 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
c040: 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
c050: 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
c060: 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
c070: 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
c080: 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
c090: 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
c0a0: 65 72 72 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 44  error.  .**.** D
c0b0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
c0c0: 61 63 74 69 6f 6e 2c 20 74 68 65 20 5b 53 51 4c  action, the [SQL
c0d0: 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20  ITE_IGNORE] and 
c0e0: 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 72 65  [SQLITE_DENY] re
c0f0: 74 75 72 6e 0a 2a 2a 20 63 6f 64 65 73 20 6d 69  turn.** codes mi
c100: 67 68 74 20 6d 65 61 6e 20 73 6f 6d 65 74 68 69  ght mean somethi
c110: 6e 67 20 64 69 66 66 65 72 65 6e 74 20 6f 72 20  ng different or 
c120: 74 68 65 79 20 6d 69 67 68 74 20 6d 65 61 6e 20  they might mean 
c130: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 68 69 6e  the same.** thin
c140: 67 2e 20 20 49 66 20 74 68 65 20 61 63 74 69 6f  g.  If the actio
c150: 6e 20 69 73 2c 20 66 6f 72 20 65 78 61 6d 70 6c  n is, for exampl
c160: 65 2c 20 74 6f 20 70 65 72 66 6f 72 6d 20 61 20  e, to perform a 
c170: 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e 2c  delete opertion,
c180: 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  .** then [SQLITE
c190: 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53 51  _IGNORE] and [SQ
c1a0: 4c 49 54 45 5f 44 45 4e 59 5d 20 62 6f 74 68 20  LITE_DENY] both 
c1b0: 63 61 75 73 65 20 74 68 65 20 73 74 61 74 65 6d  cause the statem
c1c0: 65 6e 74 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 0a  ent compilation.
c1d0: 2a 2a 20 74 6f 20 66 61 69 6c 20 77 69 74 68 20  ** to fail with 
c1e0: 61 6e 20 65 72 72 6f 72 2e 20 20 42 75 74 20 69  an error.  But i
c1f0: 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  f the action is 
c200: 74 6f 20 72 65 61 64 20 61 20 73 70 65 63 69 66  to read a specif
c210: 69 63 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 72 6f  ic column.** fro
c220: 6d 20 61 20 73 70 65 63 69 66 69 63 20 74 61 62  m a specific tab
c230: 6c 65 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  le, then [SQLITE
c240: 5f 44 45 4e 59 5d 20 77 69 6c 6c 20 63 61 75 73  _DENY] will caus
c250: 65 20 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20  e the entire.** 
c260: 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 66 61 69  statement to fai
c270: 6c 20 62 75 74 20 5b 53 51 4c 49 54 45 5f 49 47  l but [SQLITE_IG
c280: 4e 4f 52 45 5d 20 77 69 6c 6c 20 63 61 75 73 65  NORE] will cause
c290: 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f   a NULL value to
c2a0: 20 62 65 0a 2a 2a 20 72 65 61 64 20 69 6e 73 74   be.** read inst
c2b0: 65 61 64 20 6f 66 20 74 68 65 20 61 63 74 75 61  ead of the actua
c2c0: 6c 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a  l column value..
c2d0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
c2e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
c2f0: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
c300: 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
c310: 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70  f.** the third p
c320: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
c330: 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
c340: 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
c350: 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ce..** The secon
c360: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
c370: 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
c380: 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53  n integer .** [S
c390: 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
c3a0: 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
c3b0: 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
c3c0: 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
c3d0: 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  * to be authoriz
c3e0: 65 64 2e 20 20 54 68 65 20 61 76 61 69 6c 61 62  ed.  The availab
c3f0: 6c 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  le action codes 
c400: 61 72 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  are.** [SQLITE_C
c410: 4f 50 59 20 7c 20 64 6f 63 75 6d 65 6e 74 65 64  OPY | documented
c420: 20 73 65 70 61 72 61 74 65 6c 79 5d 2e 20 20 54   separately].  T
c430: 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
c440: 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65   sixth.** parame
c450: 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ters to the call
c460: 62 61 63 6b 20 61 72 65 20 73 74 72 69 6e 67 73  back are strings
c470: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
c480: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
c490: 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
c4a0: 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
c4b0: 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  rized..**.** An 
c4c0: 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
c4d0: 65 64 20 77 68 65 6e 20 70 72 65 70 61 72 69 6e  ed when preparin
c4e0: 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
c4f0: 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
c500: 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74 6f  ed.** source, to
c510: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
c520: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
c530: 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
c540: 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74 68 61  cess data.** tha
c550: 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  t they are not a
c560: 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
c570: 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
c580: 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78 65  ot try to.** exe
c590: 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
c5a0: 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
c5b0: 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
c5c0: 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
c5d0: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
c5e0: 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
c5f0: 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
c600: 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
c610: 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
c620: 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
c630: 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
c640: 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
c650: 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
c660: 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
c670: 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
c680: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
c690: 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
c6a0: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
c6b0: 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
c6c0: 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
c6d0: 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
c6e0: 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 70 72   SQL is being pr
c6f0: 65 70 61 72 65 64 20 74 68 61 74 20 64 69 73 61  epared that disa
c700: 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
c710: 0a 2a 2a 20 65 78 63 65 70 74 20 53 45 4c 45 43  .** except SELEC
c720: 54 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 0a  T statements.  .
c730: 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  **.** Only a sin
c740: 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
c750: 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
c760: 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
c770: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
c780: 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
c790: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
c7a0: 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
c7b0: 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
c7c0: 69 6f 75 73 20 63 61 6c 6c 2e 20 20 41 20 4e 55  ious call.  A NU
c7d0: 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65  LL authorizer me
c7e0: 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68  ans that no auth
c7f0: 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
c800: 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
c810: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 61  .  The default a
c820: 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c  uthorizer is NUL
c830: 4c 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  L..**.** Note th
c840: 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
c850: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
c860: 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
c870: 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  g .** [sqlite3_p
c880: 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
c890: 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
c8a0: 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
c8b0: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
c8c0: 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
c8d0: 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
c8e0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
c8f0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
c900: 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
c910: 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
c920: 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
c930: 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
c940: 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
c950: 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
c960: 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
c970: 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
c980: 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
c990: 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
c9a0: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
c9b0: 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
c9c0: 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
c9d0: 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
c9e0: 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
c9f0: 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
ca00: 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
ca10: 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
ca20: 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
ca30: 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
ca40: 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
ca50: 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
ca60: 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
ca70: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
ca80: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
ca90: 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
caa0: 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
cab0: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
cac0: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
cad0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
cae0: 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
caf0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
cb00: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
cb10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cb20: 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
cb30: 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
cb40: 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
cb50: 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
cb60: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
cb70: 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
cb80: 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
cb90: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
cba0: 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
cbb0: 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
cbc0: 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
cbd0: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
cbe0: 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
cbf0: 74 68 6f 72 69 7a 65 72 20 63 65 72 74 61 69 6e  thorizer certain
cc00: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
cc10: 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
cc20: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
cc30: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
cc40: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
cc50: 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
cc60: 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
cc70: 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
cc80: 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
cc90: 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
cca0: 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
ccb0: 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
ccc0: 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
ccd0: 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
cce0: 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
ccf0: 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
cd00: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
cd10: 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
cd20: 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e   .** authorized.
cd30: 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
cd40: 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
cd50: 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
cd60: 6e 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  n callback.** fu
cd70: 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
cd80: 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
cd90: 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
cda0: 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
cdb0: 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
cdc0: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
cdd0: 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 68  ameter.  The 5th
cde0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
cdf0: 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
ce00: 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
ce10: 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
ce20: 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
ce30: 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20  emp", .** etc.) 
ce40: 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20  if applicable.  
ce50: 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
ce60: 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
ce70: 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
ce80: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
ce90: 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
cea0: 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
ceb0: 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
cec0: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
ced0: 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
cee0: 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
cef0: 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
cf00: 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20  rectly from .** 
cf10: 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
cf20: 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
cf30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
cf40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
cf50: 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
cf60: 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
cf70: 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
cf80: 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
cf90: 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
cfa0: 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
cfb0: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
cfc0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
cfd0: 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
cfe0: 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
cff0: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
d000: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
d010: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d020: 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
d030: 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
d040: 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
d050: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
d060: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d070: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
d080: 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
d090: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
d0a0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
d0b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d0c0: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
d0d0: 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
d0e0: 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
d0f0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
d100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d110: 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
d120: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
d130: 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
d140: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
d150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d160: 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
d170: 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
d180: 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
d190: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
d1a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
d1b0: 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
d1c0: 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
d1d0: 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
d1e0: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
d1f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
d200: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
d210: 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
d220: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
d230: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
d240: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
d250: 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
d260: 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
d270: 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
d280: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
d290: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
d2a0: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
d2b0: 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
d2c0: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
d2d0: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
d2e0: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
d2f0: 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
d300: 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
d310: 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
d320: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
d330: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
d340: 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
d350: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
d360: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
d370: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
d380: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
d390: 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
d3a0: 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
d3b0: 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
d3c0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
d3d0: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
d3e0: 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
d3f0: 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
d400: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
d410: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
d420: 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
d430: 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
d440: 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
d450: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
d460: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
d470: 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
d480: 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
d490: 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
d4a0: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
d4b0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
d4c0: 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
d4d0: 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
d4e0: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
d4f0: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
d500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d510: 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
d520: 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
d530: 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
d540: 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
d550: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d560: 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
d570: 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
d580: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
d590: 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
d5a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d5b0: 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
d5c0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
d5d0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
d5e0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
d5f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d600: 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
d610: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c       22   /* NUL
d620: 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
d630: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
d640: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
d650: 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
d660: 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
d670: 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
d680: 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
d690: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
d6a0: 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
d6b0: 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
d6c0: 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
d6d0: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
d6e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
d6f0: 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
d700: 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
d710: 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
d720: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
d730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
d740: 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
d750: 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
d760: 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
d770: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
d780: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
d790: 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
d7a0: 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
d7b0: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
d7c0: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
d7d0: 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
d7e0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
d7f0: 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
d800: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
d810: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
d820: 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
d830: 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
d840: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
d850: 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
d860: 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
d870: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
d880: 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
d890: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
d8a0: 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
d8b0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
d8c0: 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
d8d0: 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
d8e0: 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d   /* Function Nam
d8f0: 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
d900: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
d910: 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
d920: 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
d930: 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
d940: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
d950: 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
d960: 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
d970: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
d980: 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
d990: 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
d9a0: 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
d9b0: 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
d9c0: 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
d9d0: 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
d9e0: 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
d9f0: 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  ents..** The cal
da00: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
da10: 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
da20: 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
da30: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 74 20 74 68  invoked.** at th
da40: 65 20 66 69 72 73 74 20 5b 73 71 6c 69 74 65 33  e first [sqlite3
da50: 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 74 68 65  _step()] for the
da60: 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
da70: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
da80: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
da90: 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
daa0: 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
dab0: 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
dac0: 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
dad0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
dae0: 6e 69 73 68 65 73 20 61 6e 64 20 69 6e 63 6c 75  nishes and inclu
daf0: 64 65 73 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  des.** informati
db00: 6f 6e 20 6f 6e 20 68 6f 77 20 6c 6f 6e 67 20 74  on on how long t
db10: 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 72 61  hat statement ra
db20: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
db30: 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41  ite3_profile() A
db40: 50 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  PI is currently 
db50: 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
db60: 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69  imental and.** i
db70: 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  s subject to cha
db80: 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  nge..*/.void *sq
db90: 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
dba0: 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
dbb0: 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
dbc0: 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
dbd0: 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
dbe0: 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
dbf0: 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
dc00: 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
dc10: 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
dc20: 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
dc30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
dc40: 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
dc50: 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68  llbacks.**.** Th
dc60: 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69  is routine confi
dc70: 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  gures a callback
dc80: 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 20   function - the 
dc90: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
dca0: 6b 20 2d 20 74 68 61 74 0a 2a 2a 20 69 73 20 69  k - that.** is i
dcb0: 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
dcc0: 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
dcd0: 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
dce0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
dcf0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ],.** [sqlite3_s
dd00: 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
dd10: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
dd20: 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
dd30: 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20 69  e for this .** i
dd40: 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
dd50: 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
dd60: 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
dd70: 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68   query..**.** Th
dd80: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
dd90: 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
dda0: 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20  nce for every N 
ddb0: 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
ddc0: 6f 70 63 6f 64 65 73 2c 0a 2a 2a 20 77 68 65 72  opcodes,.** wher
ddd0: 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
dde0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
ddf0: 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  is function. The
de00: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
de10: 63 6b 0a 2a 2a 20 69 74 73 65 6c 66 20 69 73 20  ck.** itself is 
de20: 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
de30: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
de40: 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
de50: 6e 2e 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a  n. The fourth.**
de60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
de70: 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  s function is a 
de80: 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73  void pointer pas
de90: 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72  sed to the progr
dea0: 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ess callback.** 
deb0: 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69  function each ti
dec0: 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  me it is invoked
ded0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61 6c  ..**.** If a cal
dee0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  l to [sqlite3_ex
def0: 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
df00: 73 74 65 70 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  step()], or [sql
df10: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
df20: 5d 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 20  ].** results in 
df30: 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63  fewer than N opc
df40: 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 63 75  odes being execu
df50: 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ted, then the pr
df60: 6f 67 72 65 73 73 20 0a 2a 2a 20 63 61 6c 6c 62  ogress .** callb
df70: 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76  ack is never inv
df80: 6f 6b 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e 6c  oked..** .** Onl
df90: 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
dfa0: 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ess callback fun
dfb0: 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
dfc0: 69 73 74 65 72 65 64 20 66 6f 72 20 65 61 63 68  istered for each
dfd0: 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73  .** open databas
dfe0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 45  e connection.  E
dff0: 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 73 71 6c  very call to sql
e000: 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
e010: 6e 64 6c 65 72 28 29 0a 2a 2a 20 6f 76 65 72 77  ndler().** overw
e020: 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74  rites the result
e030: 73 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  s of the previou
e040: 73 20 63 61 6c 6c 2e 0a 2a 2a 20 54 6f 20 72 65  s call..** To re
e050: 6d 6f 76 65 20 74 68 65 20 70 72 6f 67 72 65 73  move the progres
e060: 73 20 63 61 6c 6c 62 61 63 6b 20 61 6c 74 6f 67  s callback altog
e070: 65 74 68 65 72 2c 20 70 61 73 73 20 4e 55 4c 4c  ether, pass NULL
e080: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
e090: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
e0a0: 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
e0b0: 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  * If the progres
e0c0: 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
e0d0: 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65  ns a result othe
e0e0: 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 20 74  r than 0, then t
e0f0: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 71  he current .** q
e100: 75 65 72 79 20 69 73 20 69 6d 6d 65 64 69 61 74  uery is immediat
e110: 65 6c 79 20 74 65 72 6d 69 6e 61 74 65 64 20 61  ely terminated a
e120: 6e 64 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  nd any database 
e130: 63 68 61 6e 67 65 73 20 72 6f 6c 6c 65 64 20 62  changes rolled b
e140: 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  ack..** The cont
e150: 61 69 6e 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  aining [sqlite3_
e160: 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
e170: 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 0a 2a 2a  3_step()], or.**
e180: 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
e190: 62 6c 65 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  ble()] call retu
e1a0: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  rns SQLITE_INTER
e1b0: 52 55 50 54 2e 20 20 20 54 68 69 73 20 66 65 61  RUPT.   This fea
e1c0: 74 75 72 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  ture.** can be u
e1d0: 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
e1e0: 2c 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  , to implement t
e1f0: 68 65 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  he "Cancel" butt
e200: 6f 6e 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f 67 72  on on a.** progr
e210: 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 20 69  ess dialog box i
e220: 6e 20 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f 69 64  n a GUI..*/.void
e230: 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
e240: 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
e250: 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
e260: 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
e270: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e280: 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
e290: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
e2a0: 6f 6e 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 74 68  on.**.** Open th
e2b0: 65 20 73 71 6c 69 74 65 20 64 61 74 61 62 61 73  e sqlite databas
e2c0: 65 20 66 69 6c 65 20 22 66 69 6c 65 6e 61 6d 65  e file "filename
e2d0: 22 2e 20 20 54 68 65 20 22 66 69 6c 65 6e 61 6d  ".  The "filenam
e2e0: 65 22 20 69 73 20 55 54 46 2d 38 0a 2a 2a 20 65  e" is UTF-8.** e
e2f0: 6e 63 6f 64 65 64 20 66 6f 72 20 73 71 6c 69 74  ncoded for sqlit
e300: 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 55 54  e3_open() and UT
e310: 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 69 6e 20  F-16 encoded in 
e320: 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
e330: 6f 72 64 65 72 0a 2a 2a 20 66 6f 72 20 73 71 6c  order.** for sql
e340: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 20  ite3_open16().  
e350: 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61  An [sqlite3*] ha
e360: 6e 64 6c 65 20 69 73 20 72 65 74 75 72 6e 65 64  ndle is returned
e370: 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a   in *ppDb, even.
e380: 2a 2a 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  ** if an error o
e390: 63 63 75 72 73 2e 20 49 66 20 74 68 65 20 64 61  ccurs. If the da
e3a0: 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
e3b0: 20 28 6f 72 20 63 72 65 61 74 65 64 29 20 73 75   (or created) su
e3c0: 63 63 65 73 73 66 75 6c 6c 79 2c 0a 2a 2a 20 74  ccessfully,.** t
e3d0: 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  hen [SQLITE_OK] 
e3e0: 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68  is returned. Oth
e3f0: 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
e400: 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
e410: 2e 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  . The.** [sqlite
e420: 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
e430: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
e440: 28 29 5d 20 20 72 6f 75 74 69 6e 65 73 20 63 61  ()]  routines ca
e450: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
e460: 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
e470: 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
e480: 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
e490: 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ror..**.** If th
e4a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
e4b0: 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2c 20  does not exist, 
e4c0: 74 68 65 6e 20 61 20 6e 65 77 20 64 61 74 61 62  then a new datab
e4d0: 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
e4e0: 74 65 64 0a 2a 2a 20 61 73 20 6e 65 65 64 65 64  ted.** as needed
e4f0: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 65  .  The default e
e500: 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
e510: 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
e520: 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
e530: 69 74 65 33 5f 6f 70 65 6e 28 29 20 69 73 20 63  ite3_open() is c
e540: 61 6c 6c 65 64 20 61 6e 64 20 55 54 46 2d 31 36  alled and UTF-16
e550: 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
e560: 31 36 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  16 is used..**.*
e570: 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
e580: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
e590: 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
e5a0: 65 64 2c 20 72 65 73 6f 75 72 63 65 73 20 61 73  ed, resources as
e5b0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
e5c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20   the [sqlite3*] 
e5d0: 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
e5e0: 20 72 65 6c 65 61 73 65 64 20 62 79 20 70 61 73   released by pas
e5f0: 73 69 6e 67 20 69 74 20 74 6f 0a 2a 2a 20 5b 73  sing it to.** [s
e600: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
e610: 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
e620: 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
e630: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e640: 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
e650: 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
e660: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 65  sqlite3_open() e
e670: 78 63 65 70 74 20 74 68 61 74 0a 2a 2a 20 70 72  xcept that.** pr
e680: 6f 76 69 64 65 73 20 74 77 6f 20 61 64 64 69 74  ovides two addit
e690: 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
e6a0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
e6b0: 63 6f 6e 74 72 6f 6c 20 6f 76 65 72 20 74 68 65  control over the
e6c0: 0a 2a 2a 20 6e 65 77 20 64 61 74 61 62 61 73 65  .** new database
e6d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
e6e0: 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
e6f0: 72 20 63 61 6e 20 62 65 20 6f 6e 65 20 6f 66 3a  r can be one of:
e700: 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
e710: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e720: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c  N_READONLY].** <
e730: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e740: 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a 2a 20  N_READWRITE].** 
e750: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e760: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
e770: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
e780: 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ATE].** </ol>.**
e790: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 76 61  .** The first va
e7a0: 6c 75 65 20 6f 70 65 6e 73 20 74 68 65 20 64 61  lue opens the da
e7b0: 74 61 62 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79  tabase read-only
e7c0: 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
e7d0: 73 65 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 70  se does.** not p
e7e0: 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c  reviously exist,
e7f0: 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
e800: 75 72 6e 65 64 2e 20 20 54 68 65 20 73 65 63 6f  urned.  The seco
e810: 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a  nd option opens.
e820: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
e830: 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
e840: 77 72 69 74 69 6e 67 20 62 75 74 20 74 68 65 20  writing but the 
e850: 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
e860: 72 65 61 64 79 0a 2a 2a 20 65 78 69 73 74 20 6f  ready.** exist o
e870: 72 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  r an error is re
e880: 74 75 72 6e 65 64 2e 20 20 54 68 65 20 74 68 69  turned.  The thi
e890: 72 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 20  rd option opens 
e8a0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
e8b0: 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
e8c0: 77 72 69 74 69 6e 67 20 61 6e 64 20 63 72 65 61  writing and crea
e8d0: 74 65 73 20 69 74 20 69 66 20 69 74 20 64 6f 65  tes it if it doe
e8e0: 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
e8f0: 69 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72  ist..** The thir
e900: 64 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 65 68  d options is beh
e910: 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 75 73  avior that is us
e920: 65 64 20 61 6c 77 61 79 73 20 66 6f 72 20 73 71  ed always for sq
e930: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
e940: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
e950: 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
e960: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
e970: 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
e980: 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
e990: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
e9a0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
e9b0: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
e9c0: 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
e9d0: 65 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  em .** interface
e9e0: 20 74 68 61 74 20 74 68 65 20 6e 65 77 20 64 61   that the new da
e9f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ea00: 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49  n should use.  I
ea10: 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
ea20: 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e  parameter is a N
ea30: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
ea40: 20 61 20 64 65 66 61 75 6c 74 20 73 75 69 74 61   a default suita
ea50: 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 68  ble for.** the h
ea60: 6f 73 74 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  ost environment 
ea70: 69 73 20 73 75 62 73 74 69 74 75 74 65 64 2e 0a  is substituted..
ea80: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 6f 20 77 69  **.** Note to wi
ea90: 6e 64 6f 77 73 20 75 73 65 72 73 3a 20 20 54 68  ndows users:  Th
eaa0: 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
eab0: 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
eac0: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
ead0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6d  sqlite3_open() m
eae0: 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
eaf0: 74 20 77 68 61 74 65 76 65 72 20 63 6f 64 65 70  t whatever codep
eb00: 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
eb10: 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 20 46 69  .** defined.  Fi
eb20: 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
eb30: 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
eb40: 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
eb50: 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
eb60: 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
eb70: 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
eb80: 69 6e 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  into sqlite3_ope
eb90: 6e 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  n()..*/.int sqli
eba0: 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
ebb0: 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
ebc0: 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
ebd0: 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
ebe0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
ebf0: 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
ec00: 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
ec10: 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
ec20: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
ec30: 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
ec40: 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
ec50: 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
ec60: 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
ec70: 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
ec80: 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
ec90: 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
eca0: 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
ecb0: 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
ecc0: 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
ecd0: 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
ece0: 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
ecf0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
ed00: 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
ed10: 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
ed20: 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
ed30: 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
ed40: 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
ed50: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
ed60: 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
ed70: 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
ed80: 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
ed90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
eda0: 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
edb0: 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ssages.**.** The
edc0: 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
edd0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
ede0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
edf0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  .** [SQLITE_OK |
ee00: 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72   result code] or
ee10: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
ee20: 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
ee30: 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66  esult code].** f
ee40: 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
ee50: 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
ee60: 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
ee70: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
ee80: 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65  [sqlite3] handle
ee90: 20 27 64 62 27 2e 20 20 49 66 20 61 20 70 72 69   'db'.  If a pri
eea0: 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
eeb0: 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f  ed but the.** mo
eec0: 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
eed0: 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
eee0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
eef0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
ef00: 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65  ode().** is unde
ef10: 66 69 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  fined. .**.** Th
ef20: 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
ef30: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
ef40: 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
ef50: 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 61 75 67   English-langaug
ef60: 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
ef70: 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
ef80: 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
ef90: 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70  F8 or UTF16 resp
efa0: 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d  ectively..** Mem
efb0: 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
efc0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
efd0: 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
efe0: 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 20 54 68 65  internally.  The
eff0: 20 0a 2a 2a 20 73 74 72 69 6e 67 20 6d 61 79 20   .** string may 
f000: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
f010: 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
f020: 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
f030: 73 20 74 6f 20 53 51 4c 69 74 65 0a 2a 2a 20 69  s to SQLite.** i
f040: 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
f050: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 73 20  ns..**.** Calls 
f060: 74 6f 20 6d 61 6e 79 20 73 71 6c 69 74 65 33 5f  to many sqlite3_
f070: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 73 65 74 20  * functions set 
f080: 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61  the error code a
f090: 6e 64 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  nd string return
f0a0: 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
f0b0: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
f0c0: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
f0d0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
f0e0: 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 28 6f  rrmsg16()].** (o
f0f0: 76 65 72 77 72 69 74 69 6e 67 20 74 68 65 20 70  verwriting the p
f100: 72 65 76 69 6f 75 73 20 76 61 6c 75 65 73 29 2e  revious values).
f110: 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 73   Note that calls
f120: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
f130: 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  code()],.** [sql
f140: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
f150: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
f160: 6d 73 67 31 36 28 29 5d 20 74 68 65 6d 73 65 6c  msg16()] themsel
f170: 76 65 73 20 64 6f 20 6e 6f 74 20 61 66 66 65 63  ves do not affec
f180: 74 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 73  t the.** results
f190: 20 6f 66 20 66 75 74 75 72 65 20 69 6e 76 6f 63   of future invoc
f1a0: 61 74 69 6f 6e 73 2e 20 20 43 61 6c 6c 73 20 74  ations.  Calls t
f1b0: 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74  o API routines t
f1c0: 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72  hat do not retur
f1d0: 6e 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f  n.** an error co
f1e0: 64 65 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71  de (example: [sq
f1f0: 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
f200: 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 63  ()]) do not.** c
f210: 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20  hange the error 
f220: 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62 79  code returned by
f230: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20   this routine.  
f240: 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20  Interfaces that 
f250: 61 72 65 0a 2a 2a 20 6e 6f 74 20 61 73 73 6f 63  are.** not assoc
f260: 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65  iated with a spe
f270: 63 69 66 69 63 20 64 61 74 61 62 61 73 65 20 63  cific database c
f280: 6f 6e 6e 65 63 74 69 6f 6e 20 28 65 78 61 6d 70  onnection (examp
f290: 6c 65 73 3a 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  les:.** [sqlite3
f2a0: 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b  _mprintf()] or [
f2b0: 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
f2c0: 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 20 64  hared_cache()] d
f2d0: 6f 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20  o not change.** 
f2e0: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e  the return code.
f2f0: 20 20 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e    .**.** Assumin
f300: 67 20 6e 6f 20 6f 74 68 65 72 20 69 6e 74 65 72  g no other inter
f310: 76 65 6e 69 6e 67 20 73 71 6c 69 74 65 33 5f 2a  vening sqlite3_*
f320: 20 41 50 49 20 63 61 6c 6c 73 20 61 72 65 20 6d   API calls are m
f330: 61 64 65 2c 20 74 68 65 20 65 72 72 6f 72 0a 2a  ade, the error.*
f340: 2a 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20  * code returned 
f350: 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
f360: 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
f370: 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 72 72  ith the same err
f380: 6f 72 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 72  or as.** the str
f390: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
f3a0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
f3b0: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
f3c0: 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f  _errmsg16()]..*/
f3d0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
f3e0: 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
f3f0: 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
f400: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
f410: 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
f420: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
f430: 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
f440: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f450: 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
f460: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 49 6e 73  Object.**.** Ins
f470: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
f480: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 20 73  ject represent s
f490: 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
f4a0: 65 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a 20 69  ents.  This.** i
f4b0: 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
f4c0: 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
f4d0: 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
f4e0: 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53   .** "compiled S
f4f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
f500: 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
f510: 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a  atement"..** .**
f520: 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
f530: 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
f540: 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
f550: 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
f560: 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
f570: 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
f580: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
f590: 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
f5a0: 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
f5b0: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
f5c0: 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
f5d0: 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
f5e0: 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  s using.**      
f5f0: 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
f600: 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
f610: 64 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d 2e  d_* interfaces].
f620: 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
f630: 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
f640: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
f650: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
f660: 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
f670: 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
f680: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
f690: 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
f6a0: 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
f6b0: 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
f6c0: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
f6d0: 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
f6e0: 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
f6f0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
f700: 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
f710: 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
f720: 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
f730: 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
f740: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
f750: 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
f760: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
f770: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
f780: 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
f790: 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
f7a0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
f7b0: 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
f7c0: 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  ement.**.** To e
f7d0: 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
f7e0: 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
f7f0: 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
f800: 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
f810: 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
f820: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
f830: 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 54  utines. .**.** T
f840: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
f850: 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b 73 71  t "db" is an [sq
f860: 6c 69 74 65 33 20 7c 20 53 51 4c 69 74 65 20 64  lite3 | SQLite d
f870: 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d 20  atabase handle] 
f880: 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
f890: 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  m a prior call t
f8a0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
f8b0: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
f8c0: 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 54 68 65  pen16()]..** The
f8d0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f8e0: 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20 73   "zSql" is the s
f8f0: 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
f900: 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
f910: 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
f920: 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
f930: 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
f940: 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
f950: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
f960: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
f970: 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c 69  s UTF-8 and sqli
f980: 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
f990: 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
f9a0: 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
f9b0: 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
f9c0: 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
f9d0: 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a 2a 2a  ument is less.**
f9e0: 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
f9f0: 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
fa00: 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
fa10: 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
fa20: 49 66 0a 2a 2a 20 6e 42 79 74 65 20 69 73 20 6e  If.** nByte is n
fa30: 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
fa40: 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
fa50: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  mum number of .*
fa60: 2a 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f  * bytes read fro
fa70: 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42  m zSql.  When nB
fa80: 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
fa90: 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
faa0: 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
fab0: 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
fac0: 20 27 5c 30 30 30 27 20 63 68 61 72 61 63 74 65   '\000' characte
fad0: 72 20 6f 72 20 0a 2a 2a 20 75 6e 74 69 6c 20 74  r or .** until t
fae0: 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
faf0: 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
fb00: 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 2a  s first..**.** *
fb10: 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
fb20: 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
fb30: 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74  irst byte past t
fb40: 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
fb50: 72 73 74 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  rst.** SQL state
fb60: 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
fb70: 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
fb80: 20 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66 69   compiles the fi
fb90: 72 73 74 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  rst statement.**
fba0: 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
fbb0: 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
fbc0: 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65  nting to what re
fbd0: 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
fbe0: 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20  ..**.** *ppStmt 
fbf0: 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
fc00: 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 0a   to a compiled .
fc10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
fc20: 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   | SQL statement
fc30: 20 73 74 72 75 63 74 75 72 65 5d 20 74 68 61 74   structure] that
fc40: 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
fc50: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
fc60: 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72 20  e3_step()].  Or 
fc70: 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  if there is an e
fc80: 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 6d 61  rror, *ppStmt ma
fc90: 79 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f 20 4e  y be.** set to N
fca0: 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70  ULL.  If the inp
fcb0: 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 65  ut text containe
fcc0: 64 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  d no SQL (if the
fcd0: 20 69 6e 70 75 74 20 69 73 20 61 6e 64 0a 2a 2a   input is and.**
fce0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
fcf0: 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
fd00: 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
fd10: 74 6f 20 4e 55 4c 4c 2e 20 20 54 68 65 20 63 61  to NULL.  The ca
fd20: 6c 6c 69 6e 67 0a 2a 2a 20 70 72 6f 63 65 64 75  lling.** procedu
fd30: 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
fd40: 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
fd50: 68 65 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  he compiled SQL 
fd60: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69  statement.** usi
fd70: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
fd80: 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
fd90: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
fda0: 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20  th it..**.** On 
fdb0: 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45  success, [SQLITE
fdc0: 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
fdd0: 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
fde0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
fdf0: 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  R | error code] 
fe00: 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
fe10: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
fe20: 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
fe30: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
fe40: 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
fe50: 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
fe60: 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
fe70: 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
fe80: 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
fe90: 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
fea0: 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
feb0: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
fec0: 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
fed0: 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
fee0: 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e  * In the "v2" in
fef0: 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
ff00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
ff10: 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
ff20: 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
ff30: 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
ff40: 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
ff50: 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 67   of the .** orig
ff60: 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
ff70: 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
ff80: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
ff90: 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
ffa0: 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65  behave a differe
ffb0: 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73  ntly in two ways
ffc0: 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
ffd0: 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64  <li>.** If the d
ffe0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
fff0: 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
10000 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
10010 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
10020 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
10030 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
10040 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
10050 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
10060 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
10070 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
10080 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
10090 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68  ain.  If the sch
100a0 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20  ema has changed 
100b0 69 6e 20 61 20 77 61 79 0a 2a 2a 20 74 68 61 74  in a way.** that
100c0 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65   makes the state
100d0 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76  ment no longer v
100e0 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  alid, [sqlite3_s
100f0 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c  tep()] will stil
10100 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
10110 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75  ITE_SCHEMA].  Bu
10120 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67  t unlike the leg
10130 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53  acy behavior, [S
10140 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73  QLITE_SCHEMA] is
10150 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20  .** now a fatal 
10160 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20  error.  Calling 
10170 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
10180 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c  _v2()] again wil
10190 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a  l not make the.*
101a0 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e  * error go away.
101b0 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c    Note: use [sql
101c0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74  ite3_errmsg()] t
101d0 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 20  o find the text 
101e0 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 0a 2a  of the parsing.*
101f0 2a 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73  * error that res
10200 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49  ults in an [SQLI
10210 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72  TE_SCHEMA] retur
10220 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
10230 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61  * <li>.** When a
10240 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
10250 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
10260 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
10270 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
10280 69 6c 65 64 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  iled .** [SQLITE
10290 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20  _ERROR | result 
102a0 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 53 51  codes] or.** [SQ
102b0 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
102c0 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
102d0 74 20 63 6f 64 65 73 5d 20 73 75 63 68 20 61 73  t codes] such as
102e0 20 64 69 72 65 63 74 6c 79 2e 0a 2a 2a 20 54 68   directly..** Th
102f0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
10300 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69  r was that [sqli
10310 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
10320 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
10330 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49  generic.** [SQLI
10340 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
10350 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f   code and you wo
10360 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
10370 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
10380 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
10390 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  set()] in order 
103a0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
103b0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
103c0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20  the problem..** 
103d0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
103e0 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 73  epare interfaces
103f0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
10400 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
10410 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75  error is.** retu
10420 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
10430 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
10440 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
10450 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
10460 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
10470 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
10480 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
10490 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
104a0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
104b0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
104c0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
104d0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
104e0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
104f0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
10500 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
10510 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
10520 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
10530 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
10540 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
10550 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
10560 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
10570 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
10580 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
10590 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
105a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
105b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
105c0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
105d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
105e0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
105f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
10600 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
10610 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
10620 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
10630 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
10640 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
10650 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
10660 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
10670 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
10680 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
10690 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
106a0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
106b0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
106c0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
106d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
106e0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
106f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
10700 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
10710 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
10720 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
10730 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
10740 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
10750 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
10760 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
10770 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
10780 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
10790 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
107a0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
107b0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
107c0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
107d0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
107e0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
107f0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
10800 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
10810 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
10820 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
10830 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
10840 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
10850 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
10860 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
10870 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
10880 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
10890 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
108a0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
108b0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
108c0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
108d0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
108e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
108f0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
10900 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
10910 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
10920 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
10930 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
10940 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
10950 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
10960 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10970 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
10980 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
10990 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
109a0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
109b0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
109c0 69 74 20 73 74 6f 72 65 73 2e 20 20 56 61 6c 75  it stores.  Valu
109d0 65 73 20 63 61 6e 20 0a 2a 2a 20 62 65 20 69 6e  es can .** be in
109e0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
109f0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
10a00 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
10a10 72 20 4e 55 4c 4c 2e 20 20 57 68 65 6e 0a 2a 2a  r NULL.  When.**
10a20 20 70 61 73 73 69 6e 67 20 61 72 6f 75 6e 64 20   passing around 
10a30 76 61 6c 75 65 73 20 69 6e 74 65 72 6e 61 6c 6c  values internall
10a40 79 2c 20 65 61 63 68 20 76 61 6c 75 65 20 69 73  y, each value is
10a50 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 0a   represented as.
10a60 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** an instance o
10a70 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  f the sqlite3_va
10a80 6c 75 65 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74  lue object..*/.t
10a90 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
10aa0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
10ab0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10ac0 3a 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  :  SQL Function 
10ad0 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
10ae0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
10af0 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
10b00 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
10b10 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
10b20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
10b30 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41  ntext object.  A
10b40 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 75 63 68   pointer to such
10b50 20 61 6e 20 6f 62 6a 65 63 74 20 69 73 20 74 68   an object is th
10b60 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d  e.** first param
10b70 65 74 65 72 20 74 6f 20 75 73 65 72 2d 64 65 66  eter to user-def
10b80 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
10b90 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ns..*/.typedef s
10ba0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
10bb0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
10bc0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
10bd0 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e 67  PI3REF:  Binding
10be0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
10bf0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
10c00 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20  *.** In the SQL 
10c10 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f  strings input to
10c20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
10c30 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
10c40 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6f 6e 65  variants,.** one
10c50 20 6f 72 20 6d 6f 72 65 20 6c 69 74 65 72 61 6c   or more literal
10c60 73 20 63 61 6e 20 62 65 20 72 65 70 6c 61 63 65  s can be replace
10c70 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20   by a parameter 
10c80 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 0a  in one of these.
10c90 2a 2a 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20  ** forms:.**.** 
10ca0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
10cb0 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
10cc0 20 3c 6c 69 3e 20 20 3a 41 41 41 0a 2a 2a 20 3c   <li>  :AAA.** <
10cd0 6c 69 3e 20 20 40 41 41 41 0a 2a 2a 20 3c 6c 69  li>  @AAA.** <li
10ce0 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
10cf0 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61  .**.** In the pa
10d00 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68  rameter forms sh
10d10 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73  own above NNN is
10d20 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
10d30 72 61 6c 2c 0a 2a 2a 20 41 41 41 20 69 73 20 61  ral,.** AAA is a
10d40 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
10d50 64 65 6e 74 69 66 69 65 72 20 61 6e 64 20 56 56  dentifier and VV
10d60 56 20 69 73 20 61 20 76 61 72 69 61 62 6c 65 20  V is a variable 
10d70 6e 61 6d 65 20 61 63 63 6f 72 64 69 6e 67 0a 2a  name according.*
10d80 2a 20 74 6f 20 74 68 65 20 73 79 6e 74 61 78 20  * to the syntax 
10d90 72 75 6c 65 73 20 6f 66 20 74 68 65 20 54 43 4c  rules of the TCL
10da0 20 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61 6e   programming lan
10db0 67 75 61 67 65 2e 0a 2a 2a 20 54 68 65 20 76 61  guage..** The va
10dc0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20 70 61  lues of these pa
10dd0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
10de0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
10df0 6d 65 74 65 72 20 6e 61 6d 65 73 22 29 0a 2a 2a  meter names").**
10e00 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
10e10 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
10e20 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
10e30 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
10e40 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
10e50 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
10e60 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
10e70 6f 75 74 69 6e 65 73 20 61 6c 77 61 79 73 20 69  outines always i
10e80 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
10e90 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
10ea0 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
10eb0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
10ec0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
10ed0 20 6f 72 0a 2a 2a 20 69 74 73 20 76 61 72 69 61   or.** its varia
10ee0 6e 74 73 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  nts.  The second
10ef0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
10f00 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
10f10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
10f20 20 73 65 74 2e 20 20 54 68 65 20 66 69 72 73 74   set.  The first
10f30 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 0a 2a   parameter has.*
10f40 2a 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  * an index of 1.
10f50 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e   When the same n
10f60 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 69  amed parameter i
10f70 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
10f80 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 0a 2a 2a   once, second.**
10f90 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
10fa0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
10fb0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
10fc0 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
10fd0 6f 63 63 75 72 72 65 6e 63 65 2e 20 20 54 68 65  occurrence.  The
10fe0 20 69 6e 64 65 78 20 66 6f 72 0a 2a 2a 20 6e 61   index for.** na
10ff0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
11000 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
11010 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
11020 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
11030 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49  eter_name()] API
11040 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68   if desired.  Th
11050 65 20 69 6e 64 65 78 20 66 6f 72 20 22 3f 4e 4e  e index for "?NN
11060 4e 22 0a 2a 2a 20 70 61 72 61 6d 65 74 65 73 20  N".** parametes 
11070 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
11080 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20  NNN..** The NNN 
11090 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
110a0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
110b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
110c0 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45  parameter SQLITE
110d0 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
110e0 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20 76 61  MBER (default va
110f0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 20 53 65  lue: 999)..** Se
11100 65 20 3c 61 20 68 72 65 66 3d 22 6c 69 6d 69 74  e <a href="limit
11110 73 2e 68 74 6d 6c 22 3e 6c 69 6d 69 74 73 2e 68  s.html">limits.h
11120 74 6d 6c 3c 2f 61 3e 20 66 6f 72 20 61 64 64 69  tml</a> for addi
11130 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
11140 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  on..**.** The th
11150 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
11160 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
11170 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
11180 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f  er..**.** In tho
11190 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  se.** routines t
111a0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
111b0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
111c0 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d  value is the num
111d0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
111e0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
111f0 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
11200 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
11210 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
11220 20 69 6e 20 74 68 65 0a 2a 2a 20 73 74 72 69 6e   in the.** strin
11230 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
11240 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
11250 20 20 54 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20    The number.** 
11260 6f 66 20 62 79 74 65 73 20 64 6f 65 73 20 6e 6f  of bytes does no
11270 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
11280 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 61 74  ro-terminator at
11290 20 74 68 65 20 65 6e 64 20 6f 66 20 73 74 72 69   the end of stri
112a0 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  ngs..** If the f
112b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
112c0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
112d0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
112e0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75 6d 62  tring is.** numb
112f0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
11300 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
11310 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
11320 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67  ** The fifth arg
11330 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
11340 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
11350 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
11360 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
11370 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
11380 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
11390 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
113a0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
113b0 2a 20 74 65 78 74 20 61 66 74 65 72 20 53 51 4c  * text after SQL
113c0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
113d0 20 77 69 74 68 20 69 74 2e 20 20 49 66 20 74 68   with it.  If th
113e0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
113f0 20 69 73 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   is the.** speci
11400 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
11410 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 74  _STATIC], then t
11420 68 65 20 6c 69 62 72 61 72 79 20 61 73 73 75 6d  he library assum
11430 65 73 20 74 68 61 74 20 74 68 65 20 69 6e 66 6f  es that the info
11440 72 6d 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e  rmation.** is in
11450 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
11460 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
11470 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
11480 20 66 72 65 65 64 2e 20 20 49 66 20 74 68 65 0a   freed.  If the.
11490 2a 2a 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  ** fifth argumen
114a0 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
114b0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
114c0 54 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  T], then SQLite 
114d0 6d 61 6b 65 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  makes its.** own
114e0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
114f0 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
11500 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
11510 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
11520 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
11530 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
11540 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
11550 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
11560 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
11570 20 6c 65 6e 67 74 68 20 6e 20 74 68 61 74 0a 2a   length n that.*
11580 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
11590 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62   zeros.  A zerob
115a0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
115b0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
115c0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
115d0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
115e0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
115f0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
11600 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
11610 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
11620 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d   serve as place-
11630 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
11640 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
11650 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
11660 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ten using .** [s
11670 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
11680 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f   | increment BLO
11690 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
116a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
116b0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
116c0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
116d0 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71  led after.** [sq
116e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
116f0 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72  ()] (and its var
11700 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74  iants) or [sqlit
11710 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a  e3_reset()] and.
11720 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74  ** before [sqlit
11730 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42  e3_step()]..** B
11740 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
11750 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
11760 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
11770 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62   routine..** Unb
11780 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
11790 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
117a0 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  as NULL..**.** T
117b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
117c0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
117d0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
117e0 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a  n error code if.
117f0 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  ** anything goes
11800 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45   wrong.  [SQLITE
11810 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
11820 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
11830 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
11840 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
11850 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
11860 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
11870 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b  lloc fails..** [
11880 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 69  SQLITE_MISUSE] i
11890 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
118a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
118b0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 76 69 72   called on a vir
118c0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
118d0 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e  that is the wron
118e0 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68  g state or which
118f0 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
11900 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f 0a  n finalized..*/.
11910 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
11920 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
11930 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
11940 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
11950 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
11960 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
11970 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
11980 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
11990 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
119a0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
119b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
119c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
119d0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
119e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
119f0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
11a00 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
11a10 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
11a20 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
11a30 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
11a40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
11a50 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
11a60 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
11a70 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
11a80 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
11a90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
11aa0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
11ab0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
11ac0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
11ad0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
11ae0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
11af0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
11b00 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
11b10 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
11b20 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
11b30 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
11b40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11b50 4e 75 6d 62 65 72 20 4f 66 20 48 6f 73 74 20 50  Number Of Host P
11b60 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
11b70 52 65 74 75 72 6e 20 74 68 65 20 6c 61 72 67 65  Return the large
11b80 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
11b90 72 20 69 6e 64 65 78 20 69 6e 20 74 68 65 20 70  r index in the p
11ba0 72 65 63 6f 6d 70 69 6c 65 64 20 73 74 61 74 65  recompiled state
11bb0 6d 65 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 61 73  ment given.** as
11bc0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 2e 20 20   the argument.  
11bd0 57 68 65 6e 20 74 68 65 20 68 6f 73 74 20 70 61  When the host pa
11be0 72 61 6d 65 74 65 72 73 20 61 72 65 20 6f 66 20  rameters are of 
11bf0 74 68 65 20 66 6f 72 6d 73 20 6c 69 6b 65 20 22  the forms like "
11c00 3a 41 41 41 22 0a 2a 2a 20 6f 72 20 22 3f 22 2c  :AAA".** or "?",
11c10 20 74 68 65 6e 20 74 68 65 79 20 61 72 65 20 61   then they are a
11c20 73 73 69 67 6e 65 64 20 73 65 71 75 65 6e 74 69  ssigned sequenti
11c30 61 6c 20 69 6e 63 72 65 61 73 69 6e 67 20 6e 75  al increasing nu
11c40 6d 62 65 72 73 20 62 65 67 69 6e 6e 69 6e 67 0a  mbers beginning.
11c50 2a 2a 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f 20  ** with one, so 
11c60 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
11c70 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ed is the number
11c80 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 2e 20   of parameters. 
11c90 20 48 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20 74   However.** if t
11ca0 68 65 20 73 61 6d 65 20 68 6f 73 74 20 70 61 72  he same host par
11cb0 61 6d 65 74 65 72 20 6e 61 6d 65 20 69 73 20 75  ameter name is u
11cc0 73 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  sed multiple tim
11cd0 65 73 2c 20 65 61 63 68 20 6f 63 63 75 72 72 61  es, each occurra
11ce0 6e 63 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20  nce.** is given 
11cf0 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 2c  the same number,
11d00 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72 65   so the value re
11d10 74 75 72 6e 65 64 20 69 6e 20 74 68 61 74 20 63  turned in that c
11d20 61 73 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ase is the numbe
11d30 72 0a 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20 68  r.** of unique h
11d40 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
11d50 6d 65 73 2e 20 20 49 66 20 68 6f 73 74 20 70 61  mes.  If host pa
11d60 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
11d70 66 6f 72 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 61  form "?NNN".** a
11d80 72 65 20 75 73 65 64 20 28 77 68 65 72 65 20 4e  re used (where N
11d90 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  NN is an integer
11da0 29 20 74 68 65 6e 20 74 68 65 72 65 20 6d 69 67  ) then there mig
11db0 68 74 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ht be gaps in th
11dc0 65 0a 2a 2a 20 6e 75 6d 62 65 72 69 6e 67 20 61  e.** numbering a
11dd0 6e 64 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  nd the value ret
11de0 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 69 6e  urned by this in
11df0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 69  terface is the i
11e00 6e 64 65 78 20 6f 66 20 74 68 65 0a 2a 2a 20 68  ndex of the.** h
11e10 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 77 69  ost parameter wi
11e20 74 68 20 74 68 65 20 6c 61 72 67 65 73 74 20 69  th the largest i
11e30 6e 64 65 78 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ndex value..**.*
11e40 2a 20 54 68 65 20 70 72 65 70 61 72 65 64 20 73  * The prepared s
11e50 74 61 74 65 6d 65 6e 74 20 6d 75 73 74 20 6e 6f  tatement must no
11e60 74 20 6e 6f 74 20 62 65 20 5b 73 71 6c 69 74 65  t not be [sqlite
11e70 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
11e80 61 6c 69 7a 65 64 5d 0a 2a 2a 20 70 72 69 6f 72  alized].** prior
11e90 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
11ea0 20 72 65 74 75 72 6e 6e 69 6e 67 2e 20 20 4f 74   returnning.  Ot
11eb0 68 65 72 77 69 73 65 20 74 68 65 20 72 65 73 75  herwise the resu
11ec0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
11ed0 64 0a 2a 2a 20 61 6e 64 20 70 72 6f 62 61 62 6c  d.** and probabl
11ee0 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
11ef0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
11f00 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
11f10 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
11f20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
11f30 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
11f40 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a  st Parameter.**.
11f50 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
11f60 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
11f70 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66  r to the name of
11f80 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65   the n-th parame
11f90 74 65 72 20 69 6e 20 61 20 0a 2a 2a 20 5b 73 71  ter in a .** [sq
11fa0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
11fb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11fc0 2e 0a 2a 2a 20 48 6f 73 74 20 70 61 72 61 6d 65  ..** Host parame
11fd0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
11fe0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
11ff0 22 20 6f 72 20 22 24 56 56 56 22 20 68 61 76 65  " or "$VVV" have
12000 20 61 20 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68   a name.** which
12010 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
12020 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
12030 6f 72 20 22 24 56 56 56 22 2e 20 20 0a 2a 2a 20  or "$VVV".  .** 
12040 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
12050 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
12060 6f 72 20 22 24 22 20 6f 72 20 22 40 22 0a 2a 2a  or "$" or "@".**
12070 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
12080 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
12090 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20  ..** Parameters 
120a0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
120b0 6f 72 20 22 3f 4e 4e 4e 22 20 68 61 76 65 20 6e  or "?NNN" have n
120c0 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  o name..**.** Th
120d0 65 20 66 69 72 73 74 20 62 6f 75 6e 64 20 70 61  e first bound pa
120e0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
120f0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
12100 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76  ..**.** If the v
12110 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66  alue n is out of
12120 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
12130 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   n-th parameter 
12140 69 73 20 6e 61 6d 65 6c 65 73 73 2c 0a 2a 2a 20  is nameless,.** 
12150 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
12160 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75  urned.  The retu
12170 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
12180 6c 77 61 79 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lways in the.** 
12190 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
121a0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
121b0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 20 6f   parameter was o
121c0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
121d0 69 65 64 0a 2a 2a 20 61 73 20 55 54 46 2d 31 36  ied.** as UTF-16
121e0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
121f0 70 61 72 65 31 36 28 29 5d 20 6f 72 20 5b 73 71  pare16()] or [sq
12200 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
12210 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  v2()]..*/.const 
12220 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
12230 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
12240 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
12250 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
12260 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
12270 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
12280 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
12290 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
122a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  e returns the in
122b0 64 65 78 20 6f 66 20 61 20 68 6f 73 74 20 70 61  dex of a host pa
122c0 72 61 6d 65 74 65 72 20 77 69 74 68 20 74 68 65  rameter with the
122d0 20 67 69 76 65 6e 20 6e 61 6d 65 2e 0a 2a 2a 20   given name..** 
122e0 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 20 6d 61  The name must ma
122f0 74 63 68 20 65 78 61 63 74 6c 79 2e 20 20 49 66  tch exactly.  If
12300 20 6e 6f 20 70 61 72 61 6d 65 74 65 72 20 77 69   no parameter wi
12310 74 68 20 74 68 65 20 67 69 76 65 6e 20 6e 61 6d  th the given nam
12320 65 20 69 73 20 0a 2a 2a 20 66 6f 75 6e 64 2c 20  e is .** found, 
12330 72 65 74 75 72 6e 20 30 2e 20 20 50 61 72 61 6d  return 0.  Param
12340 65 74 65 72 20 6e 61 6d 65 73 20 6d 75 73 74 20  eter names must 
12350 62 65 20 55 54 46 38 2e 0a 2a 2f 0a 69 6e 74 20  be UTF8..*/.int 
12360 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
12370 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
12380 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
12390 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
123a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
123b0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
123c0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
123d0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
123e0 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68  * Contrary to th
123f0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
12400 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
12410 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a  set()] does not.
12420 2a 2a 20 72 65 73 65 74 20 74 68 65 20 5b 73 71  ** reset the [sq
12430 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
12440 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
12450 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
12460 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
12470 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73 65 20 74  atement].  Use t
12480 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a  his routine to.*
12490 2a 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  * reset all host
124a0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
124b0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
124c0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
124d0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
124e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
124f0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
12500 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
12510 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75  t Set.**.** Retu
12520 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
12530 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
12540 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
12550 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b  ned by the .** [
12560 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63  sqlite3_stmt | c
12570 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
12580 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75  ement]. This rou
12590 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 0a 2a  tine returns 0.*
125a0 2a 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  * if pStmt is an
125b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
125c0 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
125d0 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 0a 2a  urn data (for .*
125e0 2a 20 65 78 61 6d 70 6c 65 20 61 6e 20 55 50 44  * example an UPD
125f0 41 54 45 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ATE)..*/.int sql
12600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
12610 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
12620 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
12630 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
12640 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
12650 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73  t Set.**.** Thes
12660 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
12670 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
12680 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
12690 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
126a0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
126b0 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  of a SELECT stat
126c0 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  ement.  The sqli
126d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
126e0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
126f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
12700 20 74 6f 20 61 20 55 54 46 38 20 73 74 72 69 6e   to a UTF8 strin
12710 67 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  g and sqlite3_co
12720 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a  lumn_name16().**
12730 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
12740 65 72 20 74 6f 20 61 20 55 54 46 31 36 20 73 74  er to a UTF16 st
12750 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74  ring.  The first
12760 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
12770 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  e.** [sqlite3_st
12780 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
12790 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6d  atement] that im
127a0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 53 45 4c  plements the SEL
127b0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  ECT statement..*
127c0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
127d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 63 6f  ameter is the co
127e0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68  lumn number.  Th
127f0 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
12800 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20  mn is.** number 
12810 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74  0..**.** The ret
12820 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
12830 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
12840 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 0a  til either the .
12850 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
12860 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
12870 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
12880 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
12890 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f  finalize()].** o
128a0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
128b0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
128c0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
128d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
128e0 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65  me16().** on the
128f0 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
12900 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d  .** If sqlite3_m
12910 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
12920 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
12930 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
12940 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
12950 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
12960 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
12970 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
12980 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
12990 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
129a0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
129b0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
129c0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
129d0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
129e0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
129f0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
12a00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
12a10 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
12a20 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
12a30 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
12a40 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54  y Result.**.** T
12a50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
12a60 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
12a70 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20   determine what 
12a80 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a  column of what.*
12a90 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68  * table in which
12aa0 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75   database a resu
12ab0 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73  lt of a SELECT s
12ac0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66  tatement comes f
12ad0 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  rom..** The name
12ae0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
12af0 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
12b00 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
12b10 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
12b20 20 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 36   a UTF8 or UTF16
12b30 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64   string.  The _d
12b40 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
12b50 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
12b60 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
12b70 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
12b80 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
12b90 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
12ba0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
12bb0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
12bc0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
12bd0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
12be0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
12bf0 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ntil.** the [sql
12c00 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
12c10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12c20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  is destroyed usi
12c30 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
12c40 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
12c50 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
12c60 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
12c70 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
12c80 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
12c90 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  coding..**.** Th
12ca0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
12cb0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
12cc0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
12cd0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
12ce0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
12cf0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
12d00 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
12d10 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77  nt to the follow
12d20 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 0a  ing calls is a .
12d30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
12d40 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20   | compiled SQL 
12d50 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54  statement]..** T
12d60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
12d70 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
12d80 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
12d90 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
12da0 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61 74 65  by .** the state
12db0 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
12dc0 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
12dd0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
12de0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20  *.** If the Nth 
12df0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
12e00 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
12e10 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
12e20 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65 72 79  n.** or subquery
12e30 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
12e40 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
12e50 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
12e60 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
12e70 6e 20 4e 55 4c 4c 2e 20 4f 74 68 65 72 77 69 73  n NULL. Otherwis
12e80 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
12e90 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  he .** name of t
12ea0 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
12eb0 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20  base, table and 
12ec0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
12ed0 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  y result.** colu
12ee0 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
12ef0 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20   from..**.** As 
12f00 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
12f10 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
12f20 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68  e postfixed with
12f30 20 22 31 36 22 20 72 65 74 75 72 6e 20 55 54 46   "16" return UTF
12f40 2d 31 36 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 73  -16.** encoded s
12f50 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65  trings, the othe
12f60 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
12f70 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
12f80 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
12f90 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
12fa0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
12fb0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
12fc0 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e  he .** SQLITE_EN
12fd0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
12fe0 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f  DATA preprocesso
12ff0 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
13000 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
13010 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
13020 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
13030 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
13040 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
13050 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
13060 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
13070 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
13080 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
13090 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
130a0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
130b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
130c0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
130d0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
130e0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
130f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
13100 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
13110 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
13120 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
13130 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
13140 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
13150 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
13160 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
13170 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
13180 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
13190 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
131a0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
131b0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
131c0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
131d0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
131e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
131f0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
13200 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
13210 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
13220 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
13230 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
13240 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
13250 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
13260 74 65 72 20 69 73 20 61 20 5b 73 71 6c 69 74 65  ter is a [sqlite
13270 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65  3_stmt | compile
13280 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d  d SQL statement]
13290 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  . .** If this st
132a0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c  atement is a SEL
132b0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  ECT statement an
132c0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
132d0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75   of the .** retu
132e0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
132f0 20 6f 66 20 74 68 61 74 20 53 45 4c 45 43 54 20   of that SELECT 
13300 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
13310 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
13320 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
13330 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
13340 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
13350 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
13360 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  mn is returned. 
13370 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
13380 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
13390 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
133a0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
133b0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
133c0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
133d0 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74  rned..** The ret
133e0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
133f0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
13400 6f 64 65 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c  oded. For exampl
13410 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 64 61 74  e, in.** the dat
13420 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
13430 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
13440 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
13450 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66  .**.** And the f
13460 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
13470 6e 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  nt compiled:.**.
13480 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
13490 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
134a0 0a 2a 2a 20 54 68 65 6e 20 74 68 69 73 20 72 6f  .** Then this ro
134b0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
134c0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
134d0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
134e0 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74  second.** result
134f0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
13500 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
13510 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
13520 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
13530 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  * (i==0)..**.** 
13540 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
13550 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
13560 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65  ing.  So just be
13570 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
13580 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
13590 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
135a0 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
135b0 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
135c0 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
135d0 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
135e0 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
135f0 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
13600 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
13610 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
13620 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
13630 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79   not static.  Ty
13640 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
13650 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
13660 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
13670 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
13680 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
13690 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
136a0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
136b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
136c0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
136d0 5f 73 74 6d 74 20 2a 2c 20 69 6e 74 20 69 29 3b  _stmt *, int i);
136e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
136f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
13700 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
13710 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a  tmt*,int);../* .
13720 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 76  ** CAPI3REF:  Ev
13730 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
13740 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
13750 74 65 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  ter an [sqlite3_
13760 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61 74 65  stmt | SQL state
13770 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
13780 72 65 70 61 72 65 64 20 77 69 74 68 20 61 20 63  repared with a c
13790 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72  all.** to either
137a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
137b0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
137c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
137d0 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66  ()] or to one of
137e0 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69  .** the legacy i
137f0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
13800 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
13810 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
13820 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  e16()],.** then 
13830 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75  this function mu
13840 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
13850 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
13860 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a  o evaluate the .
13870 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  ** statement..**
13880 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
13890 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
138a0 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  of this sqlite3_
138b0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
138c0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
138d0 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
138e0 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
138f0 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
13900 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
13910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
13920 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
13930 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
13940 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
13950 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
13960 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
13970 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
13980 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
13990 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
139a0 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
139b0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
139c0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
139d0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
139e0 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
139f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
13a00 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
13a10 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
13a20 2a 20 49 6e 20 74 68 65 20 6c 61 67 61 63 79 20  * In the lagacy 
13a30 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
13a40 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
13a50 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
13a60 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53  TE_BUSY], .** [S
13a70 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
13a80 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
13a90 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
13aa0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
13ab0 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  * With the "v2" 
13ac0 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
13ad0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c  f the other [SQL
13ae0 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
13af0 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  code].** or [SQL
13b00 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
13b10 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
13b20 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20   code] might be 
13b30 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77  returned as.** w
13b40 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ell..**.** [SQLI
13b50 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
13b60 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
13b70 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
13b80 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
13b90 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
13ba0 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
13bb0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20  do its job.  If 
13bc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
13bd0 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20   a COMMIT.** or 
13be0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
13bf0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
13c00 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
13c10 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
13c20 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
13c30 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
13c40 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49  t is not a COMMI
13c50 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  T and occurs wit
13c60 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69  hin a.** explici
13c70 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
13c80 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
13c90 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
13ca0 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
13cb0 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
13cc0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
13cd0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
13ce0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
13cf0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
13d00 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
13d10 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
13d20 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
13d30 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
13d40 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
13d50 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
13d60 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
13d70 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
13d80 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
13d90 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
13da0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
13db0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
13dc0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
13dd0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
13de0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
13df0 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20   data, then .** 
13e00 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20  [SQLITE_ROW] is 
13e10 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
13e20 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
13e30 64 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a  data is ready.**
13e40 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
13e50 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54  by the caller. T
13e60 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
13e70 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a   accessed using.
13e80 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
13e90 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c  column_int | col
13ea0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
13eb0 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
13ec0 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
13ed0 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
13ee0 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
13ef0 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a  w of data..** .*
13f00 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
13f10 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
13f20 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
13f30 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
13f40 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
13f50 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
13f60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
13f70 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
13f80 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
13f90 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
13fa0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
13fb0 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
13fc0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
13fd0 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  ()]..** With the
13fe0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
13ff0 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
14000 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65  ic error code (e
14010 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49  xample:.** [SQLI
14020 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
14030 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
14040 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
14050 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
14060 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
14070 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
14080 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
14090 6f 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  on the.** [sqlit
140a0 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
140b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
140c0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
140d0 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
140e0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
140f0 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
14100 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
14110 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
14120 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
14130 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
14140 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
14150 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
14160 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
14170 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
14180 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69  alled on a [sqli
14190 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61  te3_stmt | prepa
141a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
141b0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
141c0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
141d0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
141e0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
141f0 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20 70 72   that had .** pr
14200 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
14210 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
14220 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
14230 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
14240 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
14250 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
14260 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14270 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
14280 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
14290 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
142a0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
142b0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ime..**.** <b>Go
142c0 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
142d0 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74  ert:</b>.** In t
142e0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
142f0 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c  ace, .** the sql
14300 69 74 65 33 5f 73 74 65 70 28 29 20 41 50 49 20  ite3_step() API 
14310 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
14320 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
14330 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ode,.** [SQLITE_
14340 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
14350 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74 68 65  g any error othe
14360 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
14370 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c  USY].** and [SQL
14380 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
14390 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c  u must call [sql
143a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
143b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
143c0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
143d0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
143e0 20 74 68 65 20 73 70 65 63 69 66 69 63 0a 2a 2a   the specific.**
143f0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c   [SQLITE_ERROR |
14400 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 74   result codes] t
14410 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
14420 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
14430 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
14440 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
14450 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
14460 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
14470 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
14480 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
14490 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
144a0 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
144b0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
144c0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
144d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
144e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
144f0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
14500 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
14510 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
14520 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
14530 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14540 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  16()], then the 
14550 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69 66 69  .** more specifi
14560 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  c [SQLITE_ERROR 
14570 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  | result codes] 
14580 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
14590 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
145a0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
145b0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
145c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
145d0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
145e0 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
145f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
14600 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 0a  /*.** CAPI3REF:.
14610 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
14620 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65   number of value
14630 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  s in the current
14640 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
14650 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 66  lt set..**.** Af
14660 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ter a call to [s
14670 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
14680 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  hat returns [SQL
14690 49 54 45 5f 52 4f 57 5d 2c 20 74 68 69 73 20 72  ITE_ROW], this r
146a0 6f 75 74 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72  outine.** will r
146b0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76  eturn the same v
146c0 61 6c 75 65 20 61 73 20 74 68 65 20 5b 73 71 6c  alue as the [sql
146d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
146e0 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  t()] function..*
146f0 2a 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33  * After [sqlite3
14700 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
14710 75 72 6e 65 64 20 61 6e 20 5b 53 51 4c 49 54 45  urned an [SQLITE
14720 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
14730 42 55 53 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b  BUSY], or.** a [
14740 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65  SQLITE_ERROR | e
14750 72 72 6f 72 20 63 6f 64 65 5d 2c 20 6f 72 20 62  rror code], or b
14760 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
14770 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
14780 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  .** called on th
14790 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  e [sqlite3_stmt 
147a0 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
147b0 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69  ment] for the fi
147c0 72 73 74 20 74 69 6d 65 2c 0a 2a 2a 20 74 68 69  rst time,.** thi
147d0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
147e0 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73  s zero..*/.int s
147f0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
14800 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
14810 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
14820 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
14830 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
14840 2a 0a 2a 2a 20 45 76 65 72 79 20 76 61 6c 75 65  *.** Every value
14850 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
14860 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
14870 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
14880 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
14890 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
148a0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
148b0 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
148c0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
148d0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
148e0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
148f0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
14900 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
14910 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
14920 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
14930 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
14940 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
14950 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
14960 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
14970 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
14980 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
14990 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
149a0 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
149b0 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
149c0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
149d0 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
149e0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
149f0 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
14a00 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
14a10 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  TEXT not.** SQLI
14a20 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
14a30 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
14a40 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
14a50 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
14a60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
14a70 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
14a80 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
14a90 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
14aa0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
14ab0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
14ac0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
14ad0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
14ae0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
14af0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
14b00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
14b10 65 73 75 6c 74 73 20 56 61 6c 75 65 73 20 46 72  esults Values Fr
14b20 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  om A Query.**.**
14b30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
14b40 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
14b50 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69  on about.** a si
14b60 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
14b70 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c  he current resul
14b80 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
14b90 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63  .  In every.** c
14ba0 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
14bb0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
14bc0 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b  ter to the .** [
14bd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53  sqlite3_stmt | S
14be0 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  QL statement] th
14bf0 61 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65  at is being.** e
14c00 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
14c10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68  qlite3_stmt*] th
14c20 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
14c30 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
14c40 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
14c50 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
14c60 72 69 61 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74  riants) and.** t
14c70 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14c80 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
14c90 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
14ca0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
14cb0 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  ion .** should b
14cc0 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  e returned.  The
14cd0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
14ce0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
14cf0 73 65 74 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e  set.** has an in
14d00 64 65 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20  dex of 0..**.** 
14d10 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
14d20 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 75 72 72  ment is not curr
14d30 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
14d40 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
14d50 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c  f the.** the col
14d60 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
14d70 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
14d80 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
14d90 65 64 2e 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ed. .** These ro
14da0 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
14db0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
14dc0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
14dd0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
14de0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
14df0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
14e00 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
14e10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
14e20 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
14e30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
14e40 61 73 20 62 65 65 6e 20 63 61 6c 6c 20 73 75 62  as been call sub
14e50 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
14e60 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
14e70 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
14e80 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
14e90 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
14ea0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
14eb0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
14ec0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
14ed0 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
14ee0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
14ef0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
14f00 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
14f10 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
14f20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
14f30 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
14f40 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
14f50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
14f60 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
14f70 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
14f80 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
14f90 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
14fa0 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
14fb0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
14fc0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
14fd0 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  d.  .**.** The s
14fe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
14ff0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
15000 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
15010 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
15020 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
15030 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
15040 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
15050 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68  sult column.  Th
15060 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
15070 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
15080 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
15090 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
150a0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
150b0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
150c0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
150d0 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
150e0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
150f0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
15100 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
15110 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
15120 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
15130 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
15140 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
15150 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
15160 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
15170 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
15180 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
15190 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
151a0 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
151b0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
151c0 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
151d0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
151e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
151f0 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
15200 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
15210 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
15220 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
15230 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
15240 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
15250 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
15260 28 29 20 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  () .** routine r
15270 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
15280 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
15290 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
152a0 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  g..** If the res
152b0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
152c0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
152d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
152e0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
152f0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
15300 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
15310 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
15320 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20  of bytes..** If 
15330 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
15340 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
15350 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
15360 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
15370 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
15380 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
15390 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
153a0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
153b0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
153c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
153d0 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
153e0 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72  ..** The value r
153f0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
15400 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
15410 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o terminator at 
15420 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
15430 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63  e string.  For c
15440 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
15450 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68  e returned is th
15460 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
15470 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
15480 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
15490 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
154a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
154b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
154c0 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  16() routine is 
154d0 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74  similar to sqlit
154e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
154f0 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20  ).** but leaves 
15500 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54  the result in UT
15510 46 2d 31 36 20 69 6e 73 74 65 61 64 20 6f 66 20  F-16 instead of 
15520 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20  UTF-8.  .** The 
15530 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
15540 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
15550 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
15560 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
15570 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
15580 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
15590 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
155a0 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  te.  For.** exam
155b0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
155c0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
155d0 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
155e0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
155f0 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
15600 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
15610 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
15620 65 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20 74 68  ernally to do th
15630 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20  e conversion.** 
15640 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
15650 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
15660 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
15670 63 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68 61 74  conversions that
15680 0a 2a 2a 20 61 72 65 20 61 70 70 6c 69 65 64 3a  .** are applied:
15690 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
156a0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
156b0 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
156c0 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 20 3c  ><th> Internal <
156d0 74 68 3e 20 52 65 71 75 65 73 74 65 64 20 3c 74  th> Requested <t
156e0 68 3e 20 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  h> .** <tr><th> 
156f0 20 54 79 70 65 20 20 20 20 3c 74 68 3e 20 20 20   Type    <th>   
15700 20 54 79 70 65 20 20 20 3c 74 68 3e 20 43 6f 6e   Type   <th> Con
15710 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
15720 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
15730 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
15740 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
15750 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
15760 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
15770 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
15780 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
15790 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
157a0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
157b0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
157c0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
157d0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
157e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
157f0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
15800 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
15810 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
15820 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
15830 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
15840 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
15850 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
15860 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
15870 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
15880 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
15890 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
158a0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
158b0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
158c0 61 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45 47  ame as for INTEG
158d0 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
158e0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
158f0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
15900 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
15910 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
15920 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
15930 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
15940 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
15950 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
15960 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
15970 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
15980 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
15990 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
159a0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
159b0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
159c0 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
159d0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
159e0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
159f0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
15a00 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
15a10 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
15a20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
15a30 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
15a40 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
15a50 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
15a60 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
15a70 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
15a80 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
15a90 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
15aa0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
15ab0 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
15ac0 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
15ad0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
15ae0 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
15af0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
15b00 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
15b10 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
15b20 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
15b30 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
15b40 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
15b50 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
15b60 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
15b70 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
15b80 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
15b90 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
15ba0 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
15bb0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
15bc0 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 6e  It has its.** on
15bd0 20 65 71 75 61 76 61 6c 65 6e 74 20 69 6e 74 65   equavalent inte
15be0 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
15bf0 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
15c00 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
15c10 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
15c20 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
15c30 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
15c40 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
15c50 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
15c60 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
15c70 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
15c80 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
15c90 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
15ca0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
15cb0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
15cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
15cd0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
15ce0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
15cf0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
15d00 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
15d10 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
15d20 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72   .** Type conver
15d30 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
15d40 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
15d50 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
15d60 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
15d70 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
15d80 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68  >.** <li><p>  Th
15d90 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
15da0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
15db0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
15dc0 65 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ext() .**       
15dd0 20 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f     or sqlite3_co
15de0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
15df0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
15e00 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
15e10 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65  t.**          ne
15e20 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
15e30 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70  o the string.</p
15e40 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ></li>.**.** <li
15e50 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61  ><p>  The initia
15e60 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
15e70 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
15e80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
15e90 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
15ea0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
15eb0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
15ec0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
15ed0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
15ee0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  erted.**        
15ef0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e    to UTF-16.</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 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
15f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
15f50 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  () or.**        
15f60 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
15f70 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
15f80 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
15f90 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
15fa0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  d.**          to
15fb0 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e   UTF-8.</p></li>
15fc0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
15fd0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
15fe0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
15ff0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
16000 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
16010 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
16020 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
16030 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
16040 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
16050 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
16060 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
16070 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
16080 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c  r points to will
16090 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
160a0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
160b0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
160c0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
160d0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
160e0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
160f0 6d 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20  metime it is.** 
16100 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
16110 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
16120 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
16130 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20  re invalidated. 
16140 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65   .**.** The safe
16150 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
16160 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
16170 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
16180 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
16190 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
161a0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
161b0 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  *.**  <ul>.**  <
161c0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
161d0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
161e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
161f0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
16200 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
16210 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
16220 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
16230 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
16240 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
16250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
16260 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
16270 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
16280 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
16290 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  .**  </ul>.**.**
162a0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
162b0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
162c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
162d0 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
162e0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a  column_blob(),.*
162f0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * or sqlite3_col
16300 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
16310 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
16320 72 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65 20  result into the 
16330 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61  desired.** forma
16340 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
16350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
16360 74 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65 33  tes() or sqlite3
16370 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
16380 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65  ) to.** find the
16390 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
163a0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
163b0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
163c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
163d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
163e0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
163f0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
16400 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
16410 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a  ).  And do not.*
16420 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  * mix calls to s
16430 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
16440 78 74 31 36 28 29 20 77 69 74 68 20 63 61 6c 6c  xt16() with call
16450 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
16460 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
16470 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20  ** The pointers 
16480 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
16490 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
164a0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
164b0 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
164c0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
164d0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
164e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
164f0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
16500 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
16510 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  )] is called.  T
16520 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
16530 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
16540 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62  ings.** and blob
16550 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
16560 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
16570 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
16580 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
16590 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
165a0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
165b0 5b 73 71 6c 69 74 65 5f 63 6f 6c 75 6d 6e 5f 74  [sqlite_column_t
165c0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
165d0 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  o .** [sqlite3_f
165e0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ree()]..**.** If
165f0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
16600 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
16610 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
16620 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
16630 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
16640 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
16650 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
16660 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
16670 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
16680 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
16690 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
166a0 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
166b0 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
166c0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
166d0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
166e0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
166f0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
16700 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f  QLITE_NOMEM]..*/
16710 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
16720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
16730 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
16740 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
16750 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
16760 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
16770 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
16780 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
16790 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
167a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
167b0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
167c0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
167d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
167e0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
167f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
16800 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
16810 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
16820 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
16830 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
16840 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
16850 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
16860 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
16870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
16880 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
16890 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
168a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
168b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
168c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
168d0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
168e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
168f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
16900 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
16910 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
16920 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
16930 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
16940 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
16950 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
16960 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
16970 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
16980 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69  * The sqlite3_fi
16990 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
169a0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
169b0 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 73 71 6c  elete a .** [sql
169c0 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70  ite3_stmt | comp
169d0 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
169e0 6e 74 5d 2e 20 49 66 20 74 68 65 20 73 74 61 74  nt]. If the stat
169f0 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65  ement was.** exe
16a00 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c  cuted successful
16a10 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 75  ly, or not execu
16a20 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e  ted at all, then
16a30 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
16a40 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78  turned..** If ex
16a50 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  ecution of the s
16a60 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20  tatement failed 
16a70 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c  then an .** [SQL
16a80 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f  ITE_ERROR | erro
16a90 72 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49  r code] or [SQLI
16aa0 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
16ab0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
16ac0 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ode].** is retur
16ad0 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ned. .**.** This
16ae0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
16af0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
16b00 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65  int during the e
16b10 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a  xecution of the.
16b20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
16b30 20 7c 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   | virtual machi
16b40 6e 65 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72  ne].  If the vir
16b50 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73  tual machine has
16b60 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74   not .** complet
16b70 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65  ed execution whe
16b80 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  n this routine i
16b90 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69  s called, that i
16ba0 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e  s like.** encoun
16bb0 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20  tering an error 
16bc0 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e  or an interrupt.
16bd0 20 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f    (See [sqlite3_
16be0 69 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a  interrupt()].) .
16bf0 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70  ** Incomplete up
16c00 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c  dates may be rol
16c10 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61  led back and tra
16c20 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c  nsactions cancel
16c30 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64  led,  .** depend
16c40 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75  ing on the circu
16c50 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68  mstances, and th
16c60 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  e .** [SQLITE_ER
16c70 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ROR | result cod
16c80 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c  e] returned will
16c90 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   be [SQLITE_ABOR
16ca0 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  T]..*/.int sqlit
16cb0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
16cc0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
16cd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16ce0 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
16cf0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
16d00 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ject.**.** The s
16d10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
16d20 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
16d30 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a 2a 2a  d to reset a .**
16d40 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
16d50 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74   compiled SQL st
16d60 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e  atement] object.
16d70 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 27 73  .** back to it's
16d80 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
16d90 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
16da0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  xecuted..** Any 
16db0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
16dc0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
16dd0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
16de0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
16df0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
16e00 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
16e10 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
16e20 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
16e30 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
16e40 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
16e50 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
16e60 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 69  e bindings..*/.i
16e70 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
16e80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
16e90 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
16ea0 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
16eb0 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
16ec0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
16ed0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
16ee0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75   functions are u
16ef0 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
16f00 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
16f10 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20  egates.** or to 
16f20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
16f30 61 76 69 6f 72 20 6f 66 20 65 78 69 73 74 69 6e  avior of existin
16f40 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
16f50 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
16f60 54 68 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63  The.** differenc
16f70 65 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20 74  e only between t
16f80 68 65 20 74 77 6f 20 69 73 20 74 68 61 74 20 74  he two is that t
16f90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16fa0 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65  ter, the.** name
16fb0 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29   of the (scalar)
16fc0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
16fd0 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64  regate, is encod
16fe0 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a  ed in UTF-8 for.
16ff0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
17000 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64  e_function() and
17010 20 55 54 46 2d 31 36 20 66 6f 72 20 73 71 6c 69   UTF-16 for sqli
17020 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
17030 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  ion16()..**.** T
17040 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17050 74 20 69 73 20 74 68 65 20 5b 73 71 6c 69 74 65  t is the [sqlite
17060 33 20 7c 20 64 61 74 61 62 61 73 65 20 68 61 6e  3 | database han
17070 64 6c 65 5d 20 74 68 61 74 20 68 6f 6c 64 73 20  dle] that holds 
17080 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
17090 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
170a0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 20   is to be added 
170b0 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 20 49 66  or redefined. If
170c0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f   a single.** pro
170d0 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74  gram uses more t
170e0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
170f0 20 68 61 6e 64 6c 65 20 69 6e 74 65 72 6e 61 6c   handle internal
17100 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20  ly, then SQL.** 
17110 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
17120 72 65 67 61 74 65 73 20 6d 75 73 74 20 62 65 20  regates must be 
17130 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c  added individual
17140 6c 79 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ly to each datab
17150 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20 77 69  ase.** handle wi
17160 74 68 20 77 68 69 63 68 20 74 68 65 79 20 77 69  th which they wi
17170 6c 6c 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ll be used..**.*
17180 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17190 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
171a0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
171b0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
171c0 61 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64 65 66  ated.** or redef
171d0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e  ined..** The len
171e0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
171f0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
17200 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69  5 bytes, exclusi
17210 76 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 7a 65  ve of the .** ze
17220 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
17230 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
17240 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  me length limit 
17250 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74  is in bytes, not
17260 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20  .** characters. 
17270 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
17280 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
17290 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
172a0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
172b0 75 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49 54 45  ult in an SQLITE
172c0 5f 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a  _ERROR error..**
172d0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61  .** The third pa
172e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
172f0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
17300 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
17310 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
17320 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
17330 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
17340 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
17350 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
17360 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
17370 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
17380 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
17390 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
173a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
173b0 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
173c0 63 69 66 69 65 73 20 77 68 61 74 20 0a 2a 2a 20  cifies what .** 
173d0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
173e0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
173f0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
17400 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
17410 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
17420 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
17430 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
17440 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
17450 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
17460 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
17470 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
17480 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
17490 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
174a0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
174b0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
174c0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
174d0 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f  her.  It is allo
174e0 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  wed to.** invoke
174f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
17500 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
17510 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
17520 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
17530 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
17540 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
17550 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
17560 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
17570 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65  eTextRep..** Whe
17580 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
17590 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
175a0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
175b0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
175c0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
175d0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
175e0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
175f0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
17600 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
17610 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
17620 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
17630 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
17640 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
17650 61 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  at.** text encod
17660 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
17670 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
17680 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 0a  ument should be.
17690 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  ** [SQLITE_ANY].
176a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
176b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
176c0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
176d0 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
176e0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
176f0 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  e function can g
17700 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
17710 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
17720 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  .** [sqlite3_use
17730 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a  r_data()]..**.**
17740 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69   The seventh, ei
17750 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70  ghth and ninth p
17760 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
17770 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
17780 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
17790 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
177a0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
177b0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
177c0 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6f  QL.** function o
177d0 72 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73  r aggregate. A s
177e0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
177f0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
17800 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
17810 0a 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 63 61  .** the xFunc ca
17820 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c  llback only, NUL
17830 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c  L pointers shoul
17840 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  d be passed as t
17850 68 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  he xStep.** and 
17860 78 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  xFinal parameter
17870 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20  s. An aggregate 
17880 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
17890 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
178a0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53  ntation.** of xS
178b0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  tep and xFinal a
178c0 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62  nd NULL should b
178d0 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
178e0 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e  nc. To delete an
178f0 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 51 4c  .** existing SQL
17900 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
17910 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
17920 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  L for all three 
17930 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
17940 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  back..**.** It i
17950 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
17960 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
17970 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
17980 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
17990 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
179a0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
179b0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
179c0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
179d0 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
179e0 72 20 64 69 66 66 65 72 69 6e 67 20 70 65 72 66  r differing perf
179f0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
17a00 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69  ings.  SQLite wi
17a10 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
17a20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73  plementation mos
17a30 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
17a40 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
17a50 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
17a60 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  nction is used..
17a70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
17a80 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
17a90 20 20 73 71 6c 69 74 65 33 20 2a 2c 0a 20 20 63    sqlite3 *,.  c
17aa0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
17ab0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
17ac0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
17ad0 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20  tRep,.  void*,. 
17ae0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
17af0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
17b00 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
17b10 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
17b20 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
17b30 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
17b40 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
17b50 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
17b60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
17b70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
17b80 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
17b90 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
17ba0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
17bb0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
17bc0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
17bd0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a  xtRep,.  void*,.
17be0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
17bf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
17c00 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
17c10 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
17c20 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
17c30 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
17c40 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
17c50 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
17c60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
17c70 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
17c80 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
17c90 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
17ca0 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
17cb0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
17cc0 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
17cd0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
17ce0 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
17cf0 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
17d00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17d10 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
17d20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
17d30 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
17d40 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
17d50 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
17d60 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
17d70 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
17d80 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
17d90 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
17da0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17db0 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
17dc0 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
17dd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
17de0 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
17df0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
17e00 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
17e10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
17e20 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
17e30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17e40 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f  Obsolete Functio
17e50 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ns.**.** These f
17e60 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c  unctions are all
17e70 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20   now obsolete.  
17e80 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
17e90 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
17ea0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
17eb0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
17ec0 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   we continue to 
17ed0 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65  support.** these
17ee0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77   functions.  How
17ef0 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f  ever, new develo
17f00 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73  pment projects s
17f10 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
17f20 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
17f30 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
17f40 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
17f50 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
17f60 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
17f70 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
17f80 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
17f90 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64   you want they d
17fa0 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
17fb0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
17fc0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
17fd0 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
17fe0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
17ff0 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  _stmt*);.int sql
18000 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
18010 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
18020 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
18030 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  mt*);.int sqlite
18040 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
18050 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c  (void);.void sql
18060 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
18070 6e 75 70 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  nup(void);../*.*
18080 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
18090 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
180a0 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
180b0 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
180c0 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
180d0 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
180e0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
180f0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
18100 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
18110 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
18120 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
18130 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
18140 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
18150 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
18160 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
18170 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
18180 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
18190 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
181a0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
181b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
181c0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
181d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
181e0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
181f0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
18200 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
18210 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
18220 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
18230 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
18240 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
18250 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
18260 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
18270 65 72 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ers to.** [sqlit
18280 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
18290 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
182a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
182b0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
182c0 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
182d0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
182e0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
182f0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
18300 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
18310 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
18320 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
18330 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
18340 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
18350 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
18360 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71  sponding .** [sq
18370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
18380 62 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  b | sqlite3_colu
18390 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65  mn_* routines] e
183a0 78 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74  xcept that .** t
183b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
183c0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 73 71 6c  ke a single [sql
183d0 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 6f 69  ite3_value*] poi
183e0 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  nter instead.** 
183f0 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73  of an [sqlite3_s
18400 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
18410 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
18420 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
18430 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
18440 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
18450 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
18460 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a  a UTF16 string.*
18470 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
18480 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
18490 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
184a0 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
184b0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
184c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
184d0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
184e0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
184f0 61 63 74 20 55 54 46 31 36 20 73 74 72 69 6e 67  act UTF16 string
18500 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
18510 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
18520 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
18530 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
18540 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
18550 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
18560 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
18570 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
18580 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
18590 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
185a0 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
185b0 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
185c0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
185d0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
185e0 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
185f0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
18600 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
18610 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
18620 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
18630 6f 6e 20 28 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  on (in order.** 
18640 77 6f 72 64 73 20 69 66 20 74 68 65 20 76 61 6c  words if the val
18650 75 65 20 69 73 20 6f 72 69 67 69 6e 61 6c 20 61  ue is original a
18660 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
18670 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
18680 29 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ).** then it is 
18690 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73 65  done.  Otherwise
186a0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
186b0 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20  ccurs.  The .** 
186c0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
186d0 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
186e0 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
186f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
18700 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
18710 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
18720 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
18730 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
18740 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  t.** is returned
18750 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
18760 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
18770 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
18780 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
18790 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
187a0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
187b0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
187c0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
187d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
187e0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
187f0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
18800 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
18810 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
18820 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
18830 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20 20  lue_text16()].  
18840 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
18850 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
18860 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
18870 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
18880 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
18890 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
188a0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
188b0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a  * parameters..**
188c0 20 4f 72 2c 20 69 66 20 74 68 65 20 73 71 6c 69   Or, if the sqli
188d0 74 65 33 5f 76 61 6c 75 65 2a 20 61 72 67 75 6d  te3_value* argum
188e0 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 20 74  ent comes from t
188f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
18900 6d 6e 5f 76 61 6c 75 65 28 29 5d 0a 2a 2a 20 69  mn_value()].** i
18910 6e 74 65 72 66 61 63 65 2c 20 74 68 65 6e 20 74  nterface, then t
18920 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68  hese routines sh
18930 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 66  ould be called f
18940 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
18950 65 61 64 0a 2a 2a 20 74 68 61 74 20 72 61 6e 20  ead.** that ran 
18960 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
18970 76 61 6c 75 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  value()]..*/.con
18980 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
18990 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
189a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
189b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
189c0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
189d0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
189e0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
189f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
18a00 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
18a10 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
18a20 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
18a30 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
18a40 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
18a50 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
18a60 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
18a70 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
18a80 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
18a90 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
18aa0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
18ab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
18ac0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
18ad0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
18ae0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
18af0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
18b00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
18b10 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
18b20 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
18b30 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
18b40 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
18b50 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
18b60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
18b70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
18b80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
18b90 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
18ba0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
18bb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18bc0 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
18bd0 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
18be0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ntext.**.** The 
18bf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
18c00 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
18c10 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
18c20 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  is routine to al
18c30 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75  locate.** a stru
18c40 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e  cture for storin
18c50 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 20 20  g their state.  
18c60 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
18c70 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69  his routine.** i
18c80 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20 70  s called for a p
18c90 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
18ca0 61 74 65 2c 20 61 20 6e 65 77 20 73 74 72 75 63  ate, a new struc
18cb0 74 75 72 65 20 6f 66 20 73 69 7a 65 20 6e 42 79  ture of size nBy
18cc0 74 65 73 0a 2a 2a 20 69 73 20 61 6c 6c 6f 63 61  tes.** is alloca
18cd0 74 65 64 2c 20 7a 65 72 6f 65 64 2c 20 61 6e 64  ted, zeroed, and
18ce0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 6e 20 73   returned.  On s
18cf0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
18d00 28 66 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  (for the.** same
18d10 20 61 67 67 72 65 67 61 74 65 20 69 6e 73 74 61   aggregate insta
18d20 6e 63 65 29 20 74 68 65 20 73 61 6d 65 20 62 75  nce) the same bu
18d30 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
18d40 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
18d50 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20  ation.** of the 
18d60 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73  aggregate can us
18d70 65 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62  e the returned b
18d80 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c  uffer to accumul
18d90 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  ate data..**.** 
18da0 54 68 65 20 62 75 66 66 65 72 20 61 6c 6c 6f 63  The buffer alloc
18db0 61 74 65 64 20 69 73 20 66 72 65 65 64 20 61 75  ated is freed au
18dc0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 53  tomatically by S
18dd0 51 4c 69 74 65 20 77 68 61 6e 20 74 68 65 20 61  QLite whan the a
18de0 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72  ggregate.** quer
18df0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
18e00 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
18e10 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
18e20 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a   a copy of the .
18e30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
18e40 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
18e50 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
18e60 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
18e70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
18e80 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  e callback routi
18e90 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
18ea0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
18eb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
18ec0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
18ed0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
18ee0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
18ef0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
18f00 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
18f10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
18f20 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
18f30 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
18f40 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
18f50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
18f60 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
18f70 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
18f80 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
18f90 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 55 73  ns.**.** The pUs
18fa0 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
18fb0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
18fc0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
18fd0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
18fe0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
18ff0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
19000 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 72 65 67  s.** used to reg
19010 69 73 74 65 72 20 75 73 65 72 20 66 75 6e 63 74  ister user funct
19020 69 6f 6e 73 20 69 73 20 61 76 61 69 6c 61 62 6c  ions is availabl
19030 65 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c  e to.** the impl
19040 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
19050 65 20 66 75 6e 63 74 69 6f 6e 20 75 73 69 6e 67  e function using
19060 20 74 68 69 73 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a   this call..**.*
19070 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
19080 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
19090 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
190a0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
190b0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
190c0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
190d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
190e0 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
190f0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
19100 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
19110 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
19120 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  ta.**.** The fol
19130 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
19140 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
19150 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
19160 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
19170 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64 61  ssociate meta-da
19180 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
19190 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
191a0 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
191b0 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
191c0 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
191d0 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
191e0 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
191f0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
19200 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
19210 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
19220 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
19230 2d 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  -data may be pre
19240 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
19250 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
19260 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
19270 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
19280 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
19290 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
192a0 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
192b0 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
192c0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
192d0 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
192e0 2a 20 6d 65 74 61 2d 64 61 74 61 20 61 73 73 6f  * meta-data asso
192f0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
19300 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64  SQL value passed
19310 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20   as the regular 
19320 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61  expression.** pa
19330 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70  ttern.  The comp
19340 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
19350 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
19360 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
19370 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
19380 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
19390 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68  ction so that th
193a0 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65  e original patte
193b0 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65  rn string.** doe
193c0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
193d0 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65   recompiled on e
193e0 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  ach invocation..
193f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
19400 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
19410 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
19420 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
19430 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20  he meta-data.** 
19440 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
19450 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
19460 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 63 75   value to the cu
19470 72 72 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  rrent SQL functi
19480 6f 6e 0a 2a 2a 20 63 61 6c 6c 2c 20 77 68 65 72  on.** call, wher
19490 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
194a0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  d parameter. If 
194b0 6e 6f 20 6d 65 74 61 2d 64 61 74 61 20 68 61 73  no meta-data has
194c0 20 62 65 65 6e 20 73 65 74 20 66 6f 72 0a 2a 2a   been set for.**
194d0 20 74 68 61 74 20 76 61 6c 75 65 2c 20 74 68 65   that value, the
194e0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
194f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
19500 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
19510 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73  set_auxdata() is
19520 20 75 73 65 64 20 74 6f 20 61 73 73 6f 63 69 61   used to associa
19530 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74  te meta-data wit
19540 68 20 61 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63  h an SQL.** func
19550 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 20 54  tion argument. T
19560 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
19570 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
19580 74 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  to the meta-data
19590 0a 2a 2a 20 74 6f 20 62 65 20 61 73 73 6f 63 69  .** to be associ
195a0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74  ated with the Nt
195b0 68 20 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 20  h user function 
195c0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 2e 20  argument value. 
195d0 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61  The fourth.** pa
195e0 72 61 6d 65 74 65 72 20 73 70 65 63 69 66 69 65  rameter specifie
195f0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 74  s a destructor t
19600 68 61 74 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c  hat will be call
19610 65 64 20 6f 6e 20 74 68 65 20 6d 65 74 61 2d 0a  ed on the meta-.
19620 2a 2a 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  ** data pointer 
19630 74 6f 20 72 65 6c 65 61 73 65 20 69 74 20 77 68  to release it wh
19640 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
19650 65 72 20 72 65 71 75 69 72 65 64 2e 20 49 66 20  er required. If 
19660 74 68 65 20 0a 2a 2a 20 64 65 73 74 72 75 63 74  the .** destruct
19670 6f 72 20 69 73 20 4e 55 4c 4c 2c 20 69 74 20 69  or is NULL, it i
19680 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 2e 0a 2a  s not invoked..*
19690 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65  *.** In practice
196a0 2c 20 6d 65 74 61 2d 64 61 74 61 20 69 73 20 70  , meta-data is p
196b0 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
196c0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
196d0 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
196e0 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
196f0 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
19700 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
19710 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
19720 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61  alues and SQL va
19730 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  riables..**.** T
19740 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
19750 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
19760 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
19770 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
19780 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
19790 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
197a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
197b0 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
197c0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
197d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
197e0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
197f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 2c 20  _context*, int, 
19800 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
19810 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
19820 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
19830 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
19840 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
19850 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
19860 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
19870 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  l value for the 
19880 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
19890 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
198a0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
198b0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
198c0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
198d0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
198e0 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
198f0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
19900 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
19910 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
19920 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
19930 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
19940 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
19950 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
19960 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
19970 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
19980 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e   .** SQLITE_TRAN
19990 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
199a0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
199b0 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
199c0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
199d0 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
199e0 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
199f0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
19a00 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
19a10 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
19a20 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
19a30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
19a40 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
19a50 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
19a60 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
19a70 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
19a80 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
19a90 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
19aa0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
19ab0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
19ac0 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
19ad0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
19ae0 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
19af0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
19b00 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
19b10 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
19b20 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
19b30 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
19b40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
19b50 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
19b60 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
19b70 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
19b80 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
19b90 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
19ba0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
19bb0 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
19bc0 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
19bd0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
19be0 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
19bf0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
19c00 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
19c10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
19c20 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
19c30 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
19c40 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
19c50 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
19c60 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
19c70 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
19c80 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
19c90 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66 61  lite3_bind_*] fa
19ca0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
19cb0 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69 6e  s used.** to bin
19cc0 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
19cd0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
19ce0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19cf0 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
19d00 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
19d10 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
19d20 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75 6d  te3_bind_* docum
19d30 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a  entation] for.**
19d40 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
19d50 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
19d60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
19d70 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
19d80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
19d90 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
19da0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
19db0 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
19dc0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
19dd0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 20 20 54  an exception.  T
19de0 68 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  he.** parameter 
19df0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
19e00 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
19e10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
19e20 72 31 36 28 29 0a 2a 2a 20 69 73 20 74 68 65 20  r16().** is the 
19e30 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
19e40 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
19e50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
19e60 6c 74 5f 74 6f 6f 62 69 67 28 29 20 63 61 75 73  lt_toobig() caus
19e70 65 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  e the function i
19e80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
19e90 20 74 6f 20 74 68 72 6f 77 20 61 6e 64 20 65 72   to throw and er
19ea0 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
19eb0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
19ec0 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 0a  BLOB is to long.
19ed0 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ** to represent.
19ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
19ef0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
19f00 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
19f10 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
19f20 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
19f30 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74  unction associat
19f40 65 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ed with the [sql
19f50 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
19f60 69 6e 74 65 72 2e 0a 2a 2f 0a 76 6f 69 64 20 73  inter..*/.void s
19f70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
19f80 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
19f90 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
19fa0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
19fb0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
19fc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
19fd0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
19fe0 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
19ff0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1a000 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
1a010 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
1a020 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
1a030 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1a040 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
1a050 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
1a060 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
1a070 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1a080 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
1a090 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
1a0a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1a0b0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
1a0c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
1a0d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1a0e0 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
1a0f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
1a100 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
1a110 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1a120 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
1a130 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
1a140 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
1a150 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
1a160 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
1a170 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
1a180 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
1a190 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
1a1a0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
1a1b0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
1a1c0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
1a1d0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
1a1e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
1a1f0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
1a200 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
1a210 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
1a220 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
1a230 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
1a240 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
1a250 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
1a260 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
1a270 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
1a280 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
1a290 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
1a2a0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
1a2b0 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
1a2c0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
1a2d0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
1a2e0 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
1a2f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1a300 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
1a310 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
1a320 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
1a330 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
1a340 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
1a350 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
1a360 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d  he.** [sqlite3*]
1a370 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65   handle specifie
1a380 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
1a390 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20  rgument. .**.** 
1a3a0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
1a3b0 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
1a3c0 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66  quence is specif
1a3d0 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73  ied as a UTF-8 s
1a3e0 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
1a3f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
1a400 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
1a410 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1a420 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
1a430 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
1a440 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
1a450 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
1a460 29 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73  ).  In all cases
1a470 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20  .** the name is 
1a480 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
1a490 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
1a4a0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
1a4b0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1a4c0 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
1a4d0 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
1a4e0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
1a4f0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
1a500 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
1a510 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
1a520 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
1a530 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
1a540 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
1a550 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
1a560 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
1a570 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
1a580 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
1a590 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d  e-endian or UTF-
1a5a0 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65  16 big-endian re
1a5b0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
1a5c0 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
1a5d0 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
1a5e0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
1a5f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
1a600 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
1a610 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c  . If it is NULL,
1a620 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d   this is the sam
1a630 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68  e as deleting th
1a640 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
1a650 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74  equence (so that
1a660 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63   SQLite cannot c
1a670 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e  all it anymore).
1a680 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 75   Each time the u
1a690 73 65 72 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ser.** supplied 
1a6a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
1a6b0 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65  ked, it is passe
1a6c0 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
1a6d0 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a  void* passed as.
1a6e0 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  ** the fourth ar
1a6f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1a700 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1a710 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  on() or.** sqlit
1a720 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1a730 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66  ion16() as its f
1a740 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
1a750 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  **.** The remain
1a760 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
1a770 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69   the user-suppli
1a780 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74  ed routine are t
1a790 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65  wo strings,.** e
1a7a0 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20  ach represented 
1a7b0 62 79 20 61 20 5b 6c 65 6e 67 74 68 2c 20 64 61  by a [length, da
1a7c0 74 61 5d 20 70 61 69 72 20 61 6e 64 20 65 6e 63  ta] pair and enc
1a7d0 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f  oded in the enco
1a7e0 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73  ding.** that was
1a7f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
1a800 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68  hird argument wh
1a810 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
1a820 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a   sequence was.**
1a830 20 72 65 67 69 73 74 65 72 65 64 2e 20 54 68 65   registered. The
1a840 20 75 73 65 72 20 72 6f 75 74 69 6e 65 20 73 68   user routine sh
1a850 6f 75 6c 64 20 72 65 74 75 72 6e 20 6e 65 67 61  ould return nega
1a860 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
1a870 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68 65  sitive if.** the
1a880 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
1a890 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
1a8a0 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
1a8b0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
1a8c0 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e  .** string. i.e.
1a8d0 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49   (STRING1 - STRI
1a8e0 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NG2)..**.** The 
1a8f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1a900 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
1a910 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
1a920 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1a930 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68  n().** excapt th
1a940 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65  at it takes an e
1a950 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68  xtra argument wh
1a960 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63  ich is a destruc
1a970 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63  tor for.** the c
1a980 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  ollation.  The d
1a990 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
1a9a0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  led when the col
1a9b0 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73  lation is.** des
1a9c0 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61  troyed and is pa
1a9d0 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74  ssed a copy of t
1a9e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1a9f0 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  ter void* pointe
1aa00 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  r.** of the sqli
1aa10 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1aa20 74 69 6f 6e 5f 76 32 28 29 2e 20 20 43 6f 6c 6c  tion_v2().  Coll
1aa30 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72  ations are destr
1aa40 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65  oyed when.** the
1aa50 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
1aa60 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20   by later calls 
1aa70 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
1aa80 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
1aa90 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ons.** or when t
1aaa0 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61  he [sqlite3*] da
1aab0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73  tabase handle is
1aac0 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
1aad0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
1aae0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1aaf0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1ab00 69 6f 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ion_v2() interfa
1ab10 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ce is experiment
1ab20 61 6c 20 61 6e 64 0a 2a 2a 20 73 75 62 6a 65 63  al and.** subjec
1ab30 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
1ab40 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20  uture releases. 
1ab50 20 54 68 65 20 6f 74 68 65 72 20 63 6f 6c 6c 61   The other colla
1ab60 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 0a 2a 2a  tion creation.**
1ab70 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 73   functions are s
1ab80 74 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  table..*/.int sq
1ab90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1aba0 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
1abb0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
1abc0 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
1abd0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
1abe0 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
1abf0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
1ac00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
1ac10 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
1ac20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
1ac30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
1ac40 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
1ac50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
1ac60 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
1ac70 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
1ac80 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
1ac90 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
1aca0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
1acb0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
1acc0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
1acd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1ace0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
1acf0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
1ad00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
1ad10 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
1ad20 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
1ad30 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
1ad40 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1ad50 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
1ad60 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
1ad70 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
1ad80 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
1ad90 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20  lbacks.**.** To 
1ada0 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
1adb0 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
1adc0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
1add0 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
1ade0 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
1adf0 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
1ae00 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
1ae10 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
1ae20 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61  with the.** data
1ae30 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62  base handle to b
1ae40 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65  e called wheneve
1ae50 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
1ae60 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
1ae70 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64  e is.** required
1ae80 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
1ae90 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
1aea0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
1aeb0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
1aec0 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
1aed0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
1aee0 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
1aef0 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
1af00 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
1af10 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
1af20 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
1af30 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
1af40 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
1af50 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d  is used, the nam
1af60 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64  es.** are passed
1af70 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
1af80 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
1af90 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20  e order. A call 
1afa0 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e  to either.** fun
1afb0 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
1afc0 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
1afd0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
1afe0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1aff0 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
1b000 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
1b010 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
1b020 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
1b030 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1b040 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1b050 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
1b060 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
1b070 65 64 65 64 31 36 28 29 2e 20 54 68 65 20 73 65  eded16(). The se
1b080 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1b090 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
1b0a0 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 68 69   handle. The thi
1b0b0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
1b0c0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
1b0d0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
1b0e0 31 36 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51  16BE], or.** [SQ
1b0f0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
1b100 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
1b110 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
1b120 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
1b130 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
1b140 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
1b150 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
1b160 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
1b170 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
1b180 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
1b190 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20  sequence..**.** 
1b1a0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1b1b0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
1b1c0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
1b1d0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
1b1e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
1b1f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
1b200 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
1b210 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
1b220 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
1b230 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1b240 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
1b250 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
1b260 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
1b270 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
1b280 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
1b290 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
1b2a0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
1b2b0 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
1b2c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
1b2d0 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
1b2e0 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
1b2f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
1b300 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
1b310 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
1b320 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
1b330 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
1b340 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
1b350 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
1b360 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
1b370 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
1b380 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
1b390 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
1b3a0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
1b3b0 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
1b3c0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
1b3d0 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
1b3e0 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
1b3f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
1b400 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1b410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b420 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
1b430 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
1b440 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
1b450 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
1b460 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
1b470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
1b480 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
1b490 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
1b4a0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
1b4b0 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
1b4c0 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
1b4d0 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
1b4e0 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
1b4f0 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
1b500 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1b510 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
1b520 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
1b530 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
1b540 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
1b550 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
1b560 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
1b570 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
1b580 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
1b590 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1b5a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b5b0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
1b5c0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
1b5d0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
1b5e0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
1b5f0 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
1b600 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b610 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65  EF:  Suspend Exe
1b620 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
1b630 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68  rt Time.**.** Th
1b640 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
1b650 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
1b660 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
1b670 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 61 20   execution.** a 
1b680 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
1b690 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
1b6a0 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
1b6b0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
1b6c0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1b6d0 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
1b6e0 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
1b6f0 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73   with .** millis
1b700 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
1b710 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
1b720 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
1b730 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74  nded up to .** t
1b740 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
1b750 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
1b760 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1b770 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20   sleep actually 
1b780 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
1b790 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
1b7a0 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
1b7b0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
1b7c0 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
1b7d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b7e0 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f    Name Of The Fo
1b7f0 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
1b800 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
1b810 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61  ** If this globa
1b820 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
1b830 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
1b840 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
1b850 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
1b860 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20  a folder (a.ka. 
1b870 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
1b880 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
1b890 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
1b8a0 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  by SQLite will b
1b8b0 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
1b8c0 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20   directory.  If 
1b8d0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
1b8e0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
1b8f0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f  , then SQLite do
1b900 65 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  es a search for 
1b910 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 74  an appropriate t
1b920 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65  emporary.** file
1b930 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
1b940 2a 20 4f 6e 63 65 20 5b 73 71 6c 69 74 65 33 5f  * Once [sqlite3_
1b950 6f 70 65 6e 28 29 5d 20 68 61 73 20 62 65 65 6e  open()] has been
1b960 20 63 61 6c 6c 65 64 2c 20 63 68 61 6e 67 69 6e   called, changin
1b970 67 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  g this variable 
1b980 77 69 6c 6c 0a 2a 2a 20 69 6e 76 61 6c 69 64 61  will.** invalida
1b990 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  te the current t
1b9a0 65 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61 73  emporary databas
1b9b0 65 2c 20 69 66 20 61 6e 79 2e 20 20 47 65 6e 65  e, if any.  Gene
1b9c0 72 61 6c 6c 79 20 73 70 65 61 6b 69 6e 67 2c 0a  rally speaking,.
1b9d0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66  ** it is not saf
1b9e0 65 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 69 73  e to invoke this
1b9f0 20 72 6f 75 74 69 6e 65 20 61 66 74 65 72 20 5b   routine after [
1ba00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
1ba10 68 61 73 0a 2a 2a 20 62 65 65 6e 20 63 61 6c 6c  has.** been call
1ba20 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  ed..*/.SQLITE_EX
1ba30 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
1ba40 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
1ba50 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
1ba60 45 46 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65  EF:  Test To See
1ba70 20 49 66 20 54 68 65 20 44 61 74 61 62 73 65 20   If The Databse 
1ba80 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69  Is In Auto-Commi
1ba90 74 20 4d 6f 64 65 0a 2a 2a 0a 2a 2a 20 54 65 73  t Mode.**.** Tes
1baa0 74 20 74 6f 20 73 65 65 20 77 68 65 74 68 65 72  t to see whether
1bab0 20 6f 72 20 6e 6f 74 20 74 68 65 20 64 61 74 61   or not the data
1bac0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1bad0 69 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  is in autocommit
1bae0 0a 2a 2a 20 6d 6f 64 65 2e 20 20 52 65 74 75 72  .** mode.  Retur
1baf0 6e 20 54 52 55 45 20 69 66 20 69 74 20 69 73 20  n TRUE if it is 
1bb00 61 6e 64 20 46 41 4c 53 45 20 69 66 20 6e 6f 74  and FALSE if not
1bb10 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  .  Autocommit mo
1bb20 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64  de is on.** by d
1bb30 65 66 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d  efault.  Autocom
1bb40 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 20  mit is disabled 
1bb50 62 79 20 61 20 42 45 47 49 4e 20 73 74 61 74 65  by a BEGIN state
1bb60 6d 65 6e 74 20 61 6e 64 20 72 65 65 6e 61 62 6c  ment and reenabl
1bb70 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 6e 65 78  ed.** by the nex
1bb80 74 20 43 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c  t COMMIT or ROLL
1bb90 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  BACK..**.** If a
1bba0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
1bbb0 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
1bbc0 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
1bbd0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
1bbe0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
1bbf0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
1bc00 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
1bc10 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
1bc20 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
1bc30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
1bc40 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
1bc50 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1bc60 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20  CAPI3REF:  Find 
1bc70 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
1bc80 64 6c 65 20 41 73 73 6f 63 69 61 74 65 64 20 57  dle Associated W
1bc90 69 74 68 20 41 20 50 72 65 70 61 72 65 64 20 53  ith A Prepared S
1bca0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52  tatement.**.** R
1bcb0 65 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74  eturn the [sqlit
1bcc0 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61  e3*] database ha
1bcd0 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a  ndle to which a.
1bce0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
1bcf0 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
1bd00 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a  ement] belongs..
1bd10 2a 2a 20 54 68 69 73 20 69 73 20 74 68 65 20 73  ** This is the s
1bd20 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  ame database han
1bd30 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  dle that was.** 
1bd40 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1bd50 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
1bd60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1bd70 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1bd80 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65  .** that was use
1bd90 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20  d to create the 
1bda0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1bdb0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f   first place..*/
1bdc0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
1bdd0 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  3_db_handle(sqli
1bde0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a  te3_stmt*);.../*
1bdf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1be00 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
1be10 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
1be20 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54  allbacks.**.** T
1be30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
1be40 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1be50 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ck functions to 
1be60 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
1be70 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
1be80 6e 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65  n.** is committe
1be90 64 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b  d or rolled back
1bea0 2e 20 20 54 68 65 20 70 41 72 67 20 61 72 67 75  .  The pArg argu
1beb0 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
1bec0 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65  hrough.** to the
1bed0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74   callback.  If t
1bee0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
1bef0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
1bf00 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e  ction .** return
1bf10 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
1bf20 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
1bf30 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
1bf40 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
1bf50 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
1bf60 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
1bf70 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
1bf80 74 73 20 70 41 72 67 20 76 61 6c 75 65 20 69 73  ts pArg value is
1bf90 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74   returned..** Ot
1bfa0 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
1bfb0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1bfc0 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
1bfd0 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
1bfe0 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
1bff0 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  k..**.** For the
1c000 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
1c010 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
1c020 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
1c030 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f  have been .** ro
1c040 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
1c050 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
1c060 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
1c070 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
1c080 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
1c090 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
1c0a0 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
1c0b0 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54 68  ack to occur. Th
1c0c0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  e .** callback i
1c0d0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
1c0e0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
1c0f0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
1c100 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62  rolled.** back b
1c110 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
1c120 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1c130 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
1c140 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72 69  These are experi
1c150 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
1c160 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63  s and are subjec
1c170 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  t to change..*/.
1c180 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1c190 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
1c1a0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
1c1b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
1c1c0 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
1c1d0 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
1c1e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
1c1f0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1c200 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
1c210 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
1c220 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
1c230 0a 2a 2a 20 52 65 67 69 73 74 65 72 20 61 20 63  .** Register a c
1c240 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1c250 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
1c260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64  se connection id
1c270 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
1c280 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65  .** first argume
1c290 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  nt to be invoked
1c2a0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
1c2b0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
1c2c0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
1c2d0 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
1c2e0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
1c2f0 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
1c300 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65  function for the
1c310 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61   same .** databa
1c320 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1c330 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
1c340 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
1c350 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
1c360 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
1c370 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
1c380 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20  en a .** row is 
1c390 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
1c3a0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 68  d or deleted. Th
1c3b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1c3c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1c3d0 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66   is.** a copy of
1c3e0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
1c3f0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  ent to sqlite3_u
1c400 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68  pdate_hook(). Th
1c410 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
1c420 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  k .** argument i
1c430 73 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f  s one of SQLITE_
1c440 49 4e 53 45 52 54 2c 20 53 51 4c 49 54 45 5f 44  INSERT, SQLITE_D
1c450 45 4c 45 54 45 20 6f 72 20 53 51 4c 49 54 45 5f  ELETE or SQLITE_
1c460 55 50 44 41 54 45 2c 20 64 65 70 65 6e 64 69 6e  UPDATE, dependin
1c470 67 0a 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72  g.** on the oper
1c480 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
1c490 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74  d the callback t
1c4a0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68  o be invoked. Th
1c4b0 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20  e third and .** 
1c4c0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
1c4d0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1c4e0 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
1c4f0 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
1c500 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20  e and .** table 
1c510 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
1c520 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
1c530 2e 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  . The final call
1c540 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
1c550 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20  s .** the rowid 
1c560 6f 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74  of the row. In t
1c570 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
1c580 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
1c590 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a  e rowid after .*
1c5a0 2a 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  * the update tak
1c5b0 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
1c5c0 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
1c5d0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
1c5e0 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
1c5f0 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
1c600 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
1c610 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
1c620 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
1c630 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ce)..**.** If an
1c640 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
1c650 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
1c660 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
1c670 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
1c680 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  rned..** Otherwi
1c690 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
1c6a0 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ned..*/.void *sq
1c6b0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
1c6c0 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  k(.  sqlite3*, .
1c6d0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a    void(*)(void *
1c6e0 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74  ,int ,char const
1c6f0 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c   *,char const *,
1c700 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a  sqlite3_int64),.
1c710 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a    void*.);../*.*
1c720 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61  * CAPI3REF:  Ena
1c730 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
1c740 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
1c750 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  e.**.** This rou
1c760 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
1c770 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
1c780 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
1c790 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
1c7a0 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
1c7b0 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
1c7c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20   connections to 
1c7d0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
1c7e0 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73  e..** Sharing is
1c7f0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
1c800 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
1c810 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66   and disabled if
1c820 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
1c830 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a   is false..**.**
1c840 20 42 65 67 69 6e 6e 69 6e 67 20 69 6e 20 53 51   Beginning in SQ
1c850 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1c860 2e 30 2c 20 63 61 63 68 65 20 73 68 61 72 69 6e  .0, cache sharin
1c870 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
1c880 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72   disabled.** for
1c890 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
1c8a0 73 73 2e 20 20 49 6e 20 70 72 69 6f 72 20 76 65  ss.  In prior ve
1c8b0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1c8c0 2c 20 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a  , sharing was.**
1c8d0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
1c8e0 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
1c8f0 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
1c900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65  .**.** The cache
1c910 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
1c920 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
1c930 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
1c940 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
1c950 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1c960 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1c970 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
1c980 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
1c990 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
1c9a0 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
1c9b0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
1c9c0 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
1c9d0 6d 6f 64 65 20 74 68 61 74 20 77 61 73 0a 2a 2a  mode that was.**
1c9e0 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
1c9f0 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
1ca00 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56   opened..**.** V
1ca10 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
1ca20 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74  nnot be used wit
1ca30 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65  h a shared cache
1ca40 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a  .  When shared.*
1ca50 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
1ca60 65 64 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ed, the sqlite3_
1ca70 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20  create_module() 
1ca80 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69  API used to regi
1ca90 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20  ster.** virtual 
1caa0 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61  tables will alwa
1cab0 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
1cac0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  or..**.** This r
1cad0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
1cae0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
1caf0 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a  ared cache was.*
1cb00 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  * enabled or dis
1cb10 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c  abled successful
1cb20 6c 79 2e 20 20 41 6e 20 5b 53 51 4c 49 54 45 5f  ly.  An [SQLITE_
1cb30 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f  ERROR | error co
1cb40 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  de].** is return
1cb50 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
1cb60 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65  .** Shared cache
1cb70 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1cb80 64 65 66 61 75 6c 74 20 66 6f 72 20 62 61 63 6b  default for back
1cb90 77 61 72 64 20 63 6f 6d 70 61 74 69 62 69 6c 69  ward compatibili
1cba0 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
1cbb0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
1cbc0 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
1cbd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41  .** CAPI3REF:  A
1cbe0 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
1cbf0 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
1cc00 20 41 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65   Attempt to free
1cc10 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70   N bytes of heap
1cc20 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c   memory by deall
1cc30 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65  ocating non-esse
1cc40 6e 74 69 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ntial.** memory 
1cc50 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64  allocations held
1cc60 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
1cc70 20 6c 69 62 72 61 72 79 20 28 65 78 61 6d 70 6c   library (exampl
1cc80 65 3a 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 75 73  e: memory .** us
1cc90 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
1cca0 62 61 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d  base pages to im
1ccb0 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
1ccc0 65 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  e)..**.** This f
1ccd0 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  unction is not a
1cce0 20 70 61 72 74 20 6f 66 20 73 74 61 6e 64 61 72   part of standar
1ccf0 64 20 62 75 69 6c 64 73 2e 20 20 49 74 20 69 73  d builds.  It is
1cd00 20 6f 6e 6c 79 20 63 72 65 61 74 65 64 0a 2a 2a   only created.**
1cd10 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
1cd20 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
1cd30 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
1cd40 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 20  MORY_MANAGEMENT 
1cd50 6d 61 63 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71  macro..*/.int sq
1cd60 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
1cd70 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mory(int);../*.*
1cd80 2a 20 43 41 50 49 33 52 45 46 3a 20 20 49 6d 70  * CAPI3REF:  Imp
1cd90 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48  ose A Limit On H
1cda0 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 50  eap Size.**.** P
1cdb0 6c 61 63 65 20 61 20 22 73 6f 66 74 22 20 6c 69  lace a "soft" li
1cdc0 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e  mit on the amoun
1cdd0 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  t of heap memory
1cde0 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c   that may be all
1cdf0 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c  ocated.** by SQL
1ce00 69 74 65 2e 20 20 49 66 20 61 6e 20 69 6e 74 65  ite.  If an inte
1ce10 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rnal allocation 
1ce20 69 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a  is requested .**
1ce30 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65   that would exce
1ce40 65 64 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ed the specified
1ce50 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33   limit, [sqlite3
1ce60 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
1ce70 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  )] is.** invoked
1ce80 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1ce90 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f  es to free up so
1cea0 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20  me space before 
1ceb0 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  the allocation.*
1cec0 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a  * is made..**.**
1ced0 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61   The limit is ca
1cee0 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63  lled "soft", bec
1cef0 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33  ause if [sqlite3
1cf00 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
1cf10 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65  )] cannot.** fre
1cf20 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  e sufficient mem
1cf30 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74  ory to prevent t
1cf40 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65  he limit from be
1cf50 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a  ing exceeded,.**
1cf60 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61   the memory is a
1cf70 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20  llocated anyway 
1cf80 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  and the current 
1cf90 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
1cfa0 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61  ds..**.** A nega
1cfb0 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c  tive or zero val
1cfc0 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74  ue for N means t
1cfd0 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hat there is no 
1cfe0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
1cff0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1d000 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
1d010 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63  ] will only be c
1d020 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72  alled when memor
1d030 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a  y is exhausted..
1d040 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
1d050 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66  alue for the sof
1d060 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
1d070 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  zero..**.** SQLi
1d080 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20  te makes a best 
1d090 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20  effort to honor 
1d0a0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
1d0b0 6d 69 74 2e 20 20 42 75 74 20 69 66 20 69 74 0a  mit.  But if it.
1d0c0 2a 2a 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  ** is unable to 
1d0d0 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73  reduce memory us
1d0e0 61 67 65 20 62 65 6c 6f 77 20 74 68 65 20 73 6f  age below the so
1d0f0 66 74 20 6c 69 6d 69 74 2c 20 65 78 65 63 75 74  ft limit, execut
1d100 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  ion will.** cont
1d110 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72  inue without err
1d120 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69  or or notificati
1d130 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79  on.  This is why
1d140 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a   the limit is .*
1d150 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74  * called a "soft
1d160 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20  " limit.  It is 
1d170 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
1d180 2a 0a 2a 2a 20 54 68 65 20 73 6f 66 74 20 68 65  *.** The soft he
1d190 61 70 20 6c 69 6d 69 74 20 69 73 20 69 6d 70 6c  ap limit is impl
1d1a0 65 6d 65 6e 74 65 64 20 75 73 69 6e 67 20 74 68  emented using th
1d1b0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1d1c0 79 5f 61 6c 61 72 6d 28 29 5d 0a 2a 2a 20 69 6e  y_alarm()].** in
1d1d0 74 65 72 66 61 63 65 2e 20 20 4f 6e 6c 79 20 61  terface.  Only a
1d1e0 20 73 69 6e 67 6c 65 20 6d 65 6d 6f 72 79 20 61   single memory a
1d1f0 6c 61 72 6d 20 69 73 20 61 76 61 69 6c 61 62 6c  larm is availabl
1d200 65 20 69 6e 20 74 68 65 20 64 65 66 61 75 6c 74  e in the default
1d210 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1d220 6f 6e 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  on.  This means 
1d230 74 68 61 74 20 69 66 20 74 68 65 20 61 70 70 6c  that if the appl
1d240 69 63 61 74 69 6f 6e 20 61 6c 73 6f 20 75 73 65  ication also use
1d250 73 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  s the.** memory 
1d260 61 6c 61 72 6d 20 69 6e 74 65 72 66 61 63 65 20  alarm interface 
1d270 69 74 20 77 69 6c 6c 20 69 6e 74 65 72 66 65 72  it will interfer
1d280 65 20 77 69 74 68 20 74 68 65 20 6f 70 65 72 61  e with the opera
1d290 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 73  tion of the.** s
1d2a0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61  oft heap limit a
1d2b0 6e 64 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  nd undefined beh
1d2c0 61 76 69 6f 72 20 77 69 6c 6c 20 72 65 73 75 6c  avior will resul
1d2d0 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  t.  .**.** Prior
1d2e0 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
1d2f0 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72  on 3.5.0, this r
1d300 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73  outine only cons
1d310 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f  trained the memo
1d320 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ry.** allocated 
1d330 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
1d340 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68  ad - the same th
1d350 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68  read in which th
1d360 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75  is routine.** ru
1d370 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ns.  Beginning w
1d380 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69  ith SQLite versi
1d390 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f  on 3.5.0, the so
1d3a0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
1d3b0 0a 2a 2a 20 61 70 70 6c 69 65 64 20 63 75 6d 75  .** applied cumu
1d3c0 6c 61 74 69 76 65 6c 79 20 74 6f 20 61 6c 6c 20  latively to all 
1d3d0 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64  threads..*/.void
1d3e0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
1d3f0 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a  ap_limit(int);..
1d400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d410 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74   Extract Metadat
1d420 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e  a About A Column
1d430 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a   Of A Table.**.*
1d440 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  * This routine.*
1d450 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64  * returns meta-d
1d460 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
1d470 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
1d480 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61   specific databa
1d490 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65  se.** table acce
1d4a0 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
1d4b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   connection hand
1d4c0 6c 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  le passed as the
1d4d0 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
1d4e0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  .** argument..**
1d4f0 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69  .** The column i
1d500 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
1d510 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
1d520 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
1d530 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74  ameters to .** t
1d540 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  his function. Th
1d550 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1d560 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
1d570 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1d580 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
1d590 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72  main", "temp" or
1d5a0 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
1d5b0 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
1d5c0 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
1d5d0 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
1d5e0 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c  . If it is NULL,
1d5f0 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
1d600 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
1d610 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
1d620 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
1d630 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
1d640 74 68 6d 20 61 73 20 74 68 65 20 64 61 74 61 62  thm as the datab
1d650 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20  ase engine uses 
1d660 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75  to .** resolve u
1d670 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
1d680 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
1d690 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
1d6a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1d6b0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
1d6c0 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
1d6d0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a  e and column .**
1d6e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
1d6f0 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
1d700 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
1d710 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
1d720 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62  meters .** may b
1d730 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65  e NULL..**.** Me
1d740 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ta information i
1d750 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72  s returned by wr
1d760 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d  iting to the mem
1d770 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61  ory locations pa
1d780 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35  ssed as.** the 5
1d790 74 68 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  th and subsequen
1d7a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
1d7b0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41  this function. A
1d7c0 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20  ny of these .** 
1d7d0 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
1d7e0 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20   NULL, in which 
1d7f0 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70  case the corresp
1d800 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f  onding element o
1d810 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72  f meta .** infor
1d820 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74  mation is ommitt
1d830 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  ed..**.** <pre>.
1d840 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20 20  ** Parameter    
1d850 20 4f 75 74 70 75 74 20 54 79 70 65 20 20 20 20   Output Type    
1d860 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a    Description.**
1d870 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
1d880 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1d890 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68  ----.**.**   5th
1d8a0 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63           const c
1d8b0 68 61 72 2a 20 20 20 20 20 20 44 61 74 61 20 74  har*      Data t
1d8c0 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20  ype.**   6th    
1d8d0 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a       const char*
1d8e0 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68        Name of th
1d8f0 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  e default collat
1d900 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a  ion sequence .**
1d910 20 20 20 37 74 68 20 20 20 20 20 20 20 20 20 69     7th         i
1d920 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
1d930 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
1d940 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
1d950 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
1d960 20 20 38 74 68 20 20 20 20 20 20 20 20 20 69 6e    8th         in
1d970 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54  t              T
1d980 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d  rue if the colum
1d990 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
1d9a0 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
1d9b0 20 20 39 74 68 20 20 20 20 20 20 20 20 20 69 6e    9th         in
1d9c0 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54  t              T
1d9d0 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d  rue if the colum
1d9e0 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45  n is AUTOINCREME
1d9f0 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a  NT.** </pre>.**.
1da00 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79  **.** The memory
1da10 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
1da20 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69  he character poi
1da30 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66  nters returned f
1da40 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61  or the .** decla
1da50 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20  ration type and 
1da60 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1da70 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79  ce is valid only
1da80 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
1da90 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20  .** call to any 
1daa0 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74  sqlite API funct
1dab0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
1dac0 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c  e specified tabl
1dad0 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20  e is actually a 
1dae0 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72  view, then an er
1daf0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1db00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70  .**.** If the sp
1db10 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69  ecified column i
1db20 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22  s "rowid", "oid"
1db30 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e   or "_rowid_" an
1db40 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52  d an .** INTEGER
1db50 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c   PRIMARY KEY col
1db60 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70  umn has been exp
1db70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
1db80 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
1db90 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  t .** parameters
1dba0 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65   are set for the
1dbb0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
1dbc0 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20  ared column. If 
1dbd0 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65  there is no.** e
1dbe0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
1dbf0 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74  ed IPK column, t
1dc00 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70  hen the output p
1dc10 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
1dc20 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73  t as .** follows
1dc30 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
1dc40 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20       data type: 
1dc50 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20  "INTEGER".**    
1dc60 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
1dc70 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a  nce: "BINARY".**
1dc80 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30       not null: 0
1dc90 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20  .**     primary 
1dca0 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75  key: 1.**     au
1dcb0 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a  to increment: 0.
1dcc0 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20  ** </pre>.**.** 
1dcd0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
1dce0 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f  y load one or mo
1dcf0 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20  re schemas from 
1dd00 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20  database files. 
1dd10 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f  If an.** error o
1dd20 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69  ccurs during thi
1dd30 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  s process, or if
1dd40 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74   the requested t
1dd50 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a  able or column.*
1dd60 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e  * cannot be foun
1dd70 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72  d, an SQLITE err
1dd80 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
1dd90 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ned and an error
1dda0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74   message.** left
1ddb0 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
1ddc0 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72   handle (to be r
1ddd0 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73  etrieved using s
1dde0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29  qlite3_errmsg())
1ddf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
1de00 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
1de10 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
1de20 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
1de30 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
1de40 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
1de50 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63  METADATA preproc
1de60 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
1de70 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
1de80 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
1de90 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71  n_metadata(.  sq
1dea0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1deb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e            /* Con
1dec0 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a  nection handle *
1ded0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1dee0 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
1def0 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65  /* Database name
1df00 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f   or NULL */.  co
1df10 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
1df20 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62  Name,     /* Tab
1df30 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e  le name */.  con
1df40 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
1df50 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75  Name,    /* Colu
1df60 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61  mn name */.  cha
1df70 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61  r const **pzData
1df80 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50  Type,    /* OUTP
1df90 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74  UT: Declared dat
1dfa0 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72  a type */.  char
1dfb0 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53   const **pzCollS
1dfc0 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55  eq,     /* OUTPU
1dfd0 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  T: Collation seq
1dfe0 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  uence name */.  
1dff0 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20  int *pNotNull,  
1e000 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
1e010 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e  UTPUT: True if N
1e020 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
1e030 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69  nt exists */.  i
1e040 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c  nt *pPrimaryKey,
1e050 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
1e060 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
1e070 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20  lumn part of PK 
1e080 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69  */.  int *pAutoi
1e090 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nc              
1e0a0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
1e0b0 20 69 66 20 63 6f 6c 75 6d 73 20 69 73 20 61 75   if colums is au
1e0c0 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a  to-increment */.
1e0d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e0e0 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  EF: Load An Exte
1e0f0 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74 65  nsion.**.** Atte
1e100 6d 70 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53  mpt to load an S
1e110 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
1e120 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65  library containe
1e130 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a  d in the file.**
1e140 20 7a 46 69 6c 65 2e 20 20 54 68 65 20 65 6e 74   zFile.  The ent
1e150 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f  ry point is zPro
1e160 63 2e 20 20 7a 50 72 6f 63 20 6d 61 79 20 62 65  c.  zProc may be
1e170 20 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65   0 in which case
1e180 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20   the.** name of 
1e190 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  the entry point 
1e1a0 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c  defaults to "sql
1e1b0 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69  ite3_extension_i
1e1c0 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  nit"..**.** Retu
1e1d0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
1e1e0 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53  n success and [S
1e1f0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
1e200 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77  something goes w
1e210 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  rong..**.** If a
1e220 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
1e230 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
1e240 6f 74 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c 20  ot 0, then fill 
1e250 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a  *pzErrMsg with .
1e260 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ** error message
1e270 20 74 65 78 74 2e 20 20 54 68 65 20 63 61 6c 6c   text.  The call
1e280 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ing function sho
1e290 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
1e2a0 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69  mory.** by calli
1e2b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
1e2c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e  ()]..**.** Exten
1e2d0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
1e2e0 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
1e2f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
1e300 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
1e310 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  n()].** prior to
1e320 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50   calling this AP
1e330 49 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69  I or an error wi
1e340 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a  ll be returned..
1e350 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
1e360 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20  oad_extension(. 
1e370 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1e380 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74         /* Load t
1e390 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74  he extension int
1e3a0 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  o this database 
1e3b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20  connection */.  
1e3c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
1e3d0 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66  e,    /* Name of
1e3e0 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72   the shared libr
1e3f0 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65  ary containing e
1e400 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f  xtension */.  co
1e410 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c  nst char *zProc,
1e420 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69      /* Entry poi
1e430 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f  nt.  Derived fro
1e440 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a  m zFile if 0 */.
1e450 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73    char **pzErrMs
1e460 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65  g       /* Put e
1e470 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72  rror message her
1e480 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b  e if not 0 */.);
1e490 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e4a0 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  :  Enable Or Dis
1e4b0 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
1e4c0 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f 20  oading.**.** So 
1e4d0 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73  as not to open s
1e4e0 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e  ecurity holes in
1e4f0 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69   older applicati
1e500 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ons that are.** 
1e510 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65  unprepared to de
1e520 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f  al with extensio
1e530 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61  n loading, and a
1e540 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73  s a means of dis
1e550 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73  abling.** extens
1e560 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c  ion loading whil
1e570 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65  e evaluating use
1e580 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74  r-entered SQL, t
1e590 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  he following.** 
1e5a0 41 50 49 20 69 73 20 70 72 6f 76 69 64 65 64 20  API is provided 
1e5b0 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c  to turn the [sql
1e5c0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
1e5d0 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d  ion()] mechanism
1e5e0 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20   on and.** off. 
1e5f0 20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65   It is off by de
1e600 66 61 75 6c 74 2e 20 20 53 65 65 20 74 69 63 6b  fault.  See tick
1e610 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20  et #1863..**.** 
1e620 43 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  Call this routin
1e630 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20  e with onoff==1 
1e640 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f  to turn extensio
1e650 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20  n loading on.** 
1e660 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68  and call it with
1e670 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72   onoff==0 to tur
1e680 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67  n it back off ag
1e690 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ain..*/.int sqli
1e6a0 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
1e6b0 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
1e6c0 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
1e6d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e6e0 45 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65  EF: Make Arrange
1e6f0 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74  ments To Automat
1e700 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45  ically Load An E
1e710 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 52  xtension.**.** R
1e720 65 67 69 73 74 65 72 20 61 6e 20 65 78 74 65 6e  egister an exten
1e730 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
1e740 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74   that is automat
1e750 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a  ically invoked.*
1e760 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  * whenever a new
1e770 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e780 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75  tion is opened u
1e790 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1e7a0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1e7b0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
1e7c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1e7d0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2()]..**.** This
1e7e0 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f   API can be invo
1e7f0 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73  ked at program s
1e800 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20  tartup in order 
1e810 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f  to register.** o
1e820 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69  ne or more stati
1e830 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74  cally linked ext
1e840 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c  ensions that wil
1e850 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a  l be available.*
1e860 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74  * to all new dat
1e870 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e880 73 2e 0a 2a 2a 0a 2a 2a 20 44 75 70 6c 69 63 61  s..**.** Duplica
1e890 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72  te extensions ar
1e8a0 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61  e detected so ca
1e8b0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
1e8c0 6e 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  ne multiple.** t
1e8d0 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
1e8e0 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20  me extension is 
1e8f0 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  harmless..**.** 
1e900 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  This routine sto
1e910 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  res a pointer to
1e920 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
1e930 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74 68  n an array.** th
1e940 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66  at is obtained f
1e950 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2e 20 20 49  rom malloc().  I
1e960 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f  f you run a memo
1e970 72 79 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b  ry leak.** check
1e980 65 72 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72  er on your progr
1e990 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74  am and it report
1e9a0 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65  s a leak because
1e9b0 20 6f 66 20 74 68 69 73 0a 2a 2a 20 61 72 72 61   of this.** arra
1e9c0 79 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b  y, then invoke [
1e9d0 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d 61 74 69  sqlite3_automati
1e9e0 63 5f 65 78 74 65 6e 73 69 6f 6e 5f 72 65 73 65  c_extension_rese
1e9f0 74 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f  t()] prior.** to
1ea00 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65   shutdown to fre
1ea10 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  e the memory..**
1ea20 0a 2a 2a 20 41 75 74 6f 6d 61 74 69 63 20 65 78  .** Automatic ex
1ea30 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
1ea40 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
1ea50 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  s..**.** This in
1ea60 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
1ea70 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
1ea80 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1ea90 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69   or.** removal i
1eaa0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
1eab0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
1eac0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f  int sqlite3_auto
1ead0 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20  _extension(void 
1eae0 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a  *xEntryPoint);..
1eaf0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1eb00 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63   Reset Automatic
1eb10 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
1eb20 6e 67 0a 2a 2a 0a 2a 2a 20 44 69 73 61 62 6c 65  ng.**.** Disable
1eb30 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20   all previously 
1eb40 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d  registered autom
1eb50 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e  atic extensions.
1eb60 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e    This.** routin
1eb70 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
1eb80 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72  ect of all prior
1eb90 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d 61   [sqlite3_automa
1eba0 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  tic_extension()]
1ebb0 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a  .** calls..**.**
1ebc0 20 54 68 69 73 20 63 61 6c 6c 20 64 69 73 61 62   This call disab
1ebd0 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65 78  led automatic ex
1ebe0 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20  tensions in all 
1ebf0 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  threads..**.** T
1ec00 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1ec10 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1ec20 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
1ec30 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d  change or.** rem
1ec40 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72  oval in future r
1ec50 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
1ec60 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
1ec70 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
1ec80 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a  tension(void);..
1ec90 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52  ./*.****** EXPER
1eca0 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63  IMENTAL - subjec
1ecb0 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
1ecc0 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a  out notice *****
1ecd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20  *********.**.** 
1ece0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
1ecf0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
1ed00 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20  le mechanism is 
1ed10 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
1ed20 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
1ed30 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
1ed40 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
1ed50 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
1ed60 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
1ed70 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
1ed80 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
1ed90 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
1eda0 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
1edb0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
1edc0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
1edd0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
1ede0 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  blizes, we will 
1edf0 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
1ee00 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
1ee10 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
1ee20 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
1ee30 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
1ee40 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
1ee50 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
1ee60 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
1ee70 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
1ee80 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1ee90 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
1eea0 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
1eeb0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
1eec0 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
1eed0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
1eee0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1eef0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
1ef00 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
1ef10 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
1ef20 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
1ef30 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
1ef40 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 6d 6f 64  le;../*.** A mod
1ef50 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73 20 6f  ule is a class o
1ef60 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  f virtual tables
1ef70 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69  .  Each module i
1ef80 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20  s defined.** by 
1ef90 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
1efa0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
1efb0 75 63 74 75 72 65 2e 20 20 54 68 69 73 20 73 74  ucture.  This st
1efc0 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73  ructure consists
1efd0 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65  .** mostly of me
1efe0 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
1eff0 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  dule..*/.struct 
1f000 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
1f010 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
1f020 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65  .  int (*xCreate
1f030 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
1f040 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
1f050 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
1f060 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
1f070 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
1f080 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
1f090 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
1f0a0 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
1f0b0 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  xConnect)(sqlite
1f0c0 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
1f0d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
1f0e0 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
1f0f0 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
1f100 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
1f110 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
1f120 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
1f130 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64    int (*xBestInd
1f140 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ex)(sqlite3_vtab
1f150 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33   *pVTab, sqlite3
1f160 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20  _index_info*);. 
1f170 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65   int (*xDisconne
1f180 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ct)(sqlite3_vtab
1f190 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
1f1a0 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69  (*xDestroy)(sqli
1f1b0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
1f1c0 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  ;.  int (*xOpen)
1f1d0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
1f1e0 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74  VTab, sqlite3_vt
1f1f0 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75  ab_cursor **ppCu
1f200 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  rsor);.  int (*x
1f210 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
1f220 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
1f230 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73  int (*xFilter)(s
1f240 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
1f250 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c  or*, int idxNum,
1f260 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78   const char *idx
1f270 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Str,.           
1f280 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73       int argc, s
1f290 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61  qlite3_value **a
1f2a0 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e  rgv);.  int (*xN
1f2b0 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ext)(sqlite3_vta
1f2c0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
1f2d0 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65  t (*xEof)(sqlite
1f2e0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
1f2f0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e  .  int (*xColumn
1f300 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
1f310 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
1f320 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
1f330 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28    int (*xRowid)(
1f340 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
1f350 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  sor*, sqlite3_in
1f360 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20  t64 *pRowid);.  
1f370 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73  int (*xUpdate)(s
1f380 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69  qlite3_vtab *, i
1f390 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nt, sqlite3_valu
1f3a0 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  e **, sqlite3_in
1f3b0 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  t64 *);.  int (*
1f3c0 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f  xBegin)(sqlite3_
1f3d0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
1f3e0 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
1f3f0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
1f400 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d  );.  int (*xComm
1f410 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  it)(sqlite3_vtab
1f420 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
1f430 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c  (*xRollback)(sql
1f440 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
1f450 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64  );.  int (*xFind
1f460 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65  Function)(sqlite
1f470 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69  3_vtab *pVtab, i
1f480 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63  nt nArg, const c
1f490 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20  har *zName,.    
1f4a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f4b0 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e     void (**pxFun
1f4c0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
1f4d0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
1f4e0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20  value**),.      
1f4f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f500 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a   void **ppArg);.
1f510 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
1f520 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
1f530 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
1f540 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a  r *zNew);.};../*
1f550 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1f560 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
1f570 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62  ture and its sub
1f580 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73  structures is us
1f590 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e  ed to.** pass in
1f5a0 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61  formation into a
1f5b0 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72  nd receive the r
1f5c0 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42  eply from the xB
1f5d0 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68  estIndex.** meth
1f5e0 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  od of an sqlite3
1f5f0 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69  _module.  The fi
1f600 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70  elds under **Inp
1f610 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a  uts** are the.**
1f620 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74   inputs to xBest
1f630 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65  Index and are re
1f640 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49  ad-only.  xBestI
1f650 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73  ndex inserts its
1f660 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1f670 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a   the **Outputs**
1f680 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54   fields..**.** T
1f690 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
1f6a0 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57   array records W
1f6b0 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
1f6c0 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 0a 2a  traints of the.*
1f6d0 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20  * form:.**.**   
1f6e0 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20        column OP 
1f6f0 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65  expr.**.** Where
1f700 20 4f 50 20 69 73 20 3d 2c 20 3c 2c 20 3c 3d 2c   OP is =, <, <=,
1f710 20 3e 2c 20 6f 72 20 3e 3d 2e 20 20 54 68 65 20   >, or >=.  The 
1f720 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61  particular opera
1f730 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  tor is stored.**
1f740 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b   in aConstraint[
1f750 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78  ].op.  The index
1f760 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
1f770 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a 20  s stored in .** 
1f780 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
1f790 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61  olumn.  aConstra
1f7a0 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
1f7b0 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
1f7c0 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
1f7d0 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
1f7e0 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
1f7f0 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
1f800 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
1f810 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
1f820 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a  it cannot..**.**
1f830 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61   The optimizer a
1f840 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
1f850 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68  erts terms of th
1f860 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20  e form "expr OP 
1f870 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d  column".** and m
1f880 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c  akes other simpl
1f890 69 66 69 63 61 74 69 6e 6f 73 20 74 6f 20 74 68  ificatinos to th
1f8a0 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69  e WHERE clause i
1f8b0 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a  n an attempt to.
1f8c0 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57  ** get as many W
1f8d0 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
1f8e0 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20  s into the form 
1f8f0 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70  shown above as p
1f900 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20  ossible..** The 
1f910 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
1f920 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
1f930 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
1f940 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65  rms in the corre
1f950 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20  ct.** form that 
1f960 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 72  refer to the par
1f970 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
1f980 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72  table being quer
1f990 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72  ied..**.** Infor
1f9a0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
1f9b0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
1f9c0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
1f9d0 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63  rderBy[]..** Eac
1f9e0 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72  h term of aOrder
1f9f0 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c  By records a col
1fa00 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52  umn of the ORDER
1fa10 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a   BY clause..**.*
1fa20 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78  * The xBestIndex
1fa30 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
1fa40 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
1fa50 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
1fa60 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
1fa70 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
1fa80 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
1fa90 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65 78  r.  If argvIndex
1faa0 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  >0 then.** the r
1fab0 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  ight-hand side o
1fac0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
1fad0 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  ing aConstraint[
1fae0 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a  ] is evaluated.*
1faf0 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68  * and becomes th
1fb00 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65  e argvIndex-th e
1fb10 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49  ntry in argv.  I
1fb20 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  f aConstraintUsa
1fb30 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20  ge[].omit.** is 
1fb40 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
1fb50 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73  onstraint is ass
1fb60 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79  umed to be fully
1fb70 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a   handled by the.
1fb80 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
1fb90 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63   and is not chec
1fba0 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c  ked again by SQL
1fbb0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ite..**.** The i
1fbc0 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72  dxNum and idxPtr
1fbd0 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f   values are reco
1fbe0 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20  rded and passed 
1fbf0 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a  into xFilter..**
1fc00 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1fc10 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20  is used to free 
1fc20 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f  idxPtr if needTo
1fc30 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72  FreeIdxPtr is tr
1fc40 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72  ue..**.** The or
1fc50 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65  derByConsumed me
1fc60 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20  ans that output 
1fc70 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c  from xFilter wil
1fc80 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
1fc90 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
1fca0 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
1fcb0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
1fcc0 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
1fcd0 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
1fce0 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
1fcf0 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61  **.** The estima
1fd00 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
1fd10 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
1fd20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
1fd30 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
1fd40 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
1fd50 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
1fd60 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
1fd70 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
1fd80 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
1fd90 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
1fda0 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
1fdb0 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
1fdc0 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
1fdd0 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
1fde0 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
1fdf0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
1fe00 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
1fe10 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74  s */.  const int
1fe20 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20   nConstraint;   
1fe30 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
1fe40 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
1fe50 72 61 69 6e 74 20 2a 2f 0a 20 20 63 6f 6e 73 74  raint */.  const
1fe60 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1fe70 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
1fe80 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
1fe90 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
1fea0 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c    /* Column on l
1feb0 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
1fec0 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
1fed0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
1fee0 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a  r op;         /*
1fef0 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72   Constraint oper
1ff00 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73  ator */.     uns
1ff10 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c  igned char usabl
1ff20 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69  e;     /* True i
1ff30 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  f this constrain
1ff40 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20  t is usable */. 
1ff50 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66      int iTermOff
1ff60 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  set;          /*
1ff70 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   Used internally
1ff80 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68   - xBestIndex sh
1ff90 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20  ould ignore */. 
1ffa0 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e 73 74   } *const aConst
1ffb0 72 61 69 6e 74 3b 20 20 20 20 20 20 2f 2a 20 54  raint;      /* T
1ffc0 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c  able of WHERE cl
1ffd0 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
1ffe0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74 20   */.  const int 
1fff0 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  nOrderBy;       
20000 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65   /* Number of te
20010 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52  rms in the ORDER
20020 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20   BY clause */.  
20030 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
20040 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72  ite3_index_order
20050 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  by {.     int iC
20060 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
20070 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75      /* Column nu
20080 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73  mber */.     uns
20090 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b  igned char desc;
200a0 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66         /* True f
200b0 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20  or DESC.  False 
200c0 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20  for ASC. */.  } 
200d0 2a 63 6f 6e 73 74 20 61 4f 72 64 65 72 42 79 3b  *const aOrderBy;
200e0 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20           /* The 
200f0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
20100 2a 2f 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73  */..  /* Outputs
20110 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
20120 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
20130 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20  raint_usage {.  
20140 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b    int argvIndex;
20150 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66             /* if
20160 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20   >0, constraint 
20170 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20  is part of argv 
20180 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20  to xFilter */.  
20190 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
201a0 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f  omit;      /* Do
201b0 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74   not code a test
201c0 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72   for this constr
201d0 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e  aint */.  } *con
201e0 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  st aConstraintUs
201f0 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75  age;.  int idxNu
20200 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  m;              
20210 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64    /* Number used
20220 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65   to identify the
20230 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72   index */.  char
20240 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20   *idxStr;       
20250 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67         /* String
20260 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69  , possibly obtai
20270 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
20280 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74  _malloc */.  int
20290 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
202a0 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20  r;      /* Free 
202b0 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c  idxStr using sql
202c0 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74  ite3_free() if t
202d0 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64  rue */.  int ord
202e0 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20  erByConsumed;   
202f0 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f      /* True if o
20300 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79  utput is already
20310 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f   ordered */.  do
20320 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f  uble estimatedCo
20330 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69  st;      /* Esti
20340 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73  mated cost of us
20350 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a  ing this index *
20360 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  /.};.#define SQL
20370 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
20380 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65  AINT_EQ    2.#de
20390 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
203a0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20  X_CONSTRAINT_GT 
203b0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
203c0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
203d0 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65  AINT_LE    8.#de
203e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
203f0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20  X_CONSTRAINT_LT 
20400 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
20410 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
20420 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23  RAINT_GE    32.#
20430 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
20440 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d  DEX_CONSTRAINT_M
20450 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 54  ATCH 64../*.** T
20460 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
20470 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  sed to register 
20480 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d  a new module nam
20490 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65  e with an SQLite
204a0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
204b0 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75   Module names mu
204c0 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64  st be registered
204d0 20 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67   before creating
204e0 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20   new.** virtual 
204f0 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f  tables on the mo
20500 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20  dule, or before 
20510 75 73 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e  using preexistin
20520 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  g virtual.** tab
20530 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  les of the modul
20540 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
20550 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
20560 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
20570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
20580 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
20590 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
205a0 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
205b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
205c0 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
205d0 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
205e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
205f0 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20  te3_module *,   
20600 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
20610 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
20620 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 20  void *          
20630 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c             /* Cl
20640 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
20650 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
20660 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73  /.);../*.** This
20670 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e   routine is iden
20680 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71 6c  tical to the sql
20690 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
206a0 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f 76  le() method abov
206b0 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  e,.** except tha
206c0 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65  t it allows a de
206d0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
206e0 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69 65  n to be specifie
206f0 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e  d. It is.** even
20700 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74   more experiment
20710 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73 74  al than the rest
20720 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
20730 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69  tables API..*/.i
20740 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
20750 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73  e_module_v2(.  s
20760 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
20770 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
20780 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
20790 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
207a0 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
207b0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
207c0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
207d0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
207e0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
207f0 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20  module *,    /* 
20800 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
20810 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
20820 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20   *,             
20830 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
20840 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
20850 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20  e/xConnect */.  
20860 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
20870 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f  void*)     /* Mo
20880 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20  dule destructor 
20890 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a  function */.);..
208a0 2f 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75  /*.** Every modu
208b0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
208c0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
208d0 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  s of the followi
208e0 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  ng structure.** 
208f0 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61  to describe a pa
20900 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
20910 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  e of the module.
20920 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20    Each subclass 
20930 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 79 6c 6f  will.** be taylo
20940 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69  red to the speci
20950 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65  fic needs of the
20960 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
20970 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a 2a  tation.   The.**
20980 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73   purpose of this
20990 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74   superclass is t
209a0 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e  o define certain
209b0 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65   fields that are
209c0 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61 6c   common.** to al
209d0 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  l module impleme
209e0 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  ntations..**.** 
209f0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d  Virtual tables m
20a00 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61  ethods can set a
20a10 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
20a20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a  by assigning a.*
20a30 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  * string obtaine
20a40 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
20a50 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72 72  printf() to zErr
20a60 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64  Msg.  The method
20a70 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20   should.** take 
20a80 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72  care that any pr
20a90 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72  ior string is fr
20aa0 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f  eed by a call to
20ab0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 0a   sqlite3_free().
20ac0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69  ** prior to assi
20ad0 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69  gning a new stri
20ae0 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  ng to zErrMsg.  
20af0 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  After the error 
20b00 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65  message.** is de
20b10 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68  livered up to th
20b20 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61  e client applica
20b30 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67  tion, the string
20b40 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
20b50 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20  ically.** freed 
20b60 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  by sqlite3_free(
20b70 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73  ) and the zErrMs
20b80 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20  g field will be 
20b90 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a  zeroed.  Note.**
20ba0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d 70   that sqlite3_mp
20bb0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
20bc0 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20 75  te3_free() are u
20bd0 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 4d  sed on the zErrM
20be0 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e 63  sg field.** sinc
20bf0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  e virtual tables
20c00 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d   are commonly im
20c10 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f 61  plemented in loa
20c20 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73  dable extensions
20c30 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74   which.** do not
20c40 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f 20   have access to 
20c50 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 29  sqlite3MPrintf()
20c60 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65 28   or sqlite3Free(
20c70 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  )..*/.struct sql
20c80 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f  ite3_vtab {.  co
20c90 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
20ca0 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a  le *pModule;  /*
20cb0 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20   The module for 
20cc0 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62  this virtual tab
20cd0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66  le */.  int nRef
20ce0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
20cf0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
20d00 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20  internally */.  
20d10 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20  char *zErrMsg;  
20d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20d30 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65  /* Error message
20d40 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70   from sqlite3_mp
20d50 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20  rintf() */.  /* 
20d60 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
20d70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
20d80 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
20d90 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
20da0 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76 65  ds */.};../* Eve
20db0 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ry module implem
20dc0 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
20dd0 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20  subclass of the 
20de0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
20df0 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69  ure.** to descri
20e00 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20  be cursors that 
20e10 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76  point into the v
20e20 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64  irtual table and
20e30 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20   are used.** to 
20e40 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65  loop through the
20e50 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20   virtual table. 
20e60 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65   Cursors are cre
20e70 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ated using the.*
20e80 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f  * xOpen method o
20e90 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45  f the module.  E
20ea0 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ach module imple
20eb0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64  mentation will d
20ec0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e  efine.** the con
20ed0 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72  tent of a cursor
20ee0 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75   structure to su
20ef0 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73  it its own needs
20f00 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70  ..**.** This sup
20f10 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69  erclass exists i
20f20 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e  n order to defin
20f30 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20  e fields of the 
20f40 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61  cursor that.** a
20f50 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c  re common to all
20f60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
20f70 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
20f80 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
20f90 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62  {.  sqlite3_vtab
20fa0 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a   *pVtab;      /*
20fb0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f   Virtual table o
20fc0 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f  f this cursor */
20fd0 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61  .  /* Virtual ta
20fe0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
20ff0 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c  ons will typical
21000 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ly add additiona
21010 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a  l fields */.};..
21020 2f 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74  /*.** The xCreat
21030 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d  e and xConnect m
21040 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75  ethods of a modu
21050 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f  le use the follo
21060 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64  wing API.** to d
21070 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61  eclare the forma
21080 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64  t (the names and
21090 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68   datatypes of th
210a0 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a  e columns) of.**
210b0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
210c0 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65  les they impleme
210d0 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  nt..*/.int sqlit
210e0 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
210f0 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
21100 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62  char *zCreateTab
21110 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72 74  le);../*.** Virt
21120 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70  ual tables can p
21130 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69  rovide alternati
21140 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
21150 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ns of functions.
21160 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46 69  ** using the xFi
21170 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f  ndFunction metho
21180 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76  d.  But global v
21190 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65  ersions of those
211a0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75   functions.** mu
211b0 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65  st exist in orde
211c0 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64  r to be overload
211d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  ed..**.** This A
211e0 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20  PI makes sure a 
211f0 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f  global version o
21200 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  f a function wit
21210 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
21220 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65  * name and numbe
21230 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
21240 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73  exists.  If no s
21250 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69  uch function exi
21260 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  sts.** before th
21270 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64  is API is called
21280 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  , a new function
21290 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68   is created.  Th
212a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
212b0 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66  .** of the new f
212c0 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63  unction always c
212d0 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69  auses an excepti
212e0 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e  on to be thrown.
212f0 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20    So.** the new 
21300 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  function is not 
21310 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e  good for anythin
21320 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74  g by itself.  It
21330 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73  s only.** purpos
21340 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61  e is to be a pla
21350 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74 69  ce-holder functi
21360 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  on that can be o
21370 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20  verloaded.** by 
21380 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a  virtual tables..
21390 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73  **.** This API s
213a0 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65  hould be conside
213b0 72 65 64 20 70 61 72 74 20 6f 66 20 74 68 65 20  red part of the 
213c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
213d0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63  terface,.** whic
213e0 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  h is experimenta
213f0 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f  l and subject to
21400 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
21410 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64  sqlite3_overload
21420 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65  _function(sqlite
21430 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
21440 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e  zFuncName, int n
21450 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  Arg);../*.** The
21460 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
21470 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
21480 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65  mechanism define
21490 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70  d above (back up
214a0 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74  .** to a comment
214b0 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69   remarkably simi
214c0 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29  lar to this one)
214d0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
214e0 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62  nsidered.** to b
214f0 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  e experimental. 
21500 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d   The interface m
21510 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69  ight change in i
21520 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73  ncompatible ways
21530 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20  ..** If this is 
21540 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f  a problem for yo
21550 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68  u, do not use th
21560 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74  e interface at t
21570 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  his time..**.** 
21580 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c  When the virtual
21590 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
215a0 20 73 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77   stablizes, we w
215b0 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a  ill declare the.
215c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78  ** interface fix
215d0 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69  ed, support it i
215e0 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64  ndefinitely, and
215f0 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d   remove this com
21600 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20  ment..**.****** 
21610 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73  EXPERIMENTAL - s
21620 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
21630 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20   without notice 
21640 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
21650 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
21660 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41  F: A Handle To A
21670 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a  n Open BLOB.**.*
21680 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
21690 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f   the following o
216a0 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
216b0 69 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a 20 72  is used to .** r
216c0 65 70 72 65 73 65 6e 74 20 61 6e 20 62 6c 6f 62  epresent an blob
216d0 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62 6c 6f 62  -handle.  A blob
216e0 2d 68 61 6e 64 6c 65 20 69 73 20 63 72 65 61 74  -handle is creat
216f0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
21700 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61  3_blob_open()] a
21710 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  nd destroyed by 
21720 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
21730 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  ose()]..** The [
21740 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
21750 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
21760 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
21770 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61  interfaces.** ca
21780 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61  n be used to rea
21790 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c  d or write small
217a0 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20   subsections of 
217b0 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68 65  the blob..** The
217c0 20 5b 73 71 6c 74 69 65 33 5f 62 6c 6f 62 5f 73   [sqltie3_blob_s
217d0 69 7a 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ize()] interface
217e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   returns the siz
217f0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c 6f 62  e of the.** blob
21800 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79   in bytes..*/.ty
21810 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
21820 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65  ite3_blob sqlite
21830 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_blob;../*.** C
21840 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20  API3REF: Open A 
21850 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65  BLOB For Increme
21860 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 4f  ntal I/O.**.** O
21870 70 65 6e 20 61 20 68 61 6e 64 6c 65 20 74 6f 20  pen a handle to 
21880 74 68 65 20 62 6c 6f 62 20 6c 6f 63 61 74 65 64  the blob located
21890 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20 63   in row iRow,, c
218a0 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 0a  olumn zColumn, .
218b0 2a 2a 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20  ** table zTable 
218c0 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 2e  in database zDb.
218d0 20 69 2e 65 2e 20 74 68 65 20 73 61 6d 65 20 62   i.e. the same b
218e0 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c 64 0a 2a  lob that would.*
218f0 2a 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79  * be selected by
21900 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
21910 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c       SELECT zCol
21920 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61  umn FROM zDb.zTa
21930 62 6c 65 20 57 48 45 52 45 20 72 6f 77 69 64 20  ble WHERE rowid 
21940 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65  = iRow;.** </pre
21950 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  >.**.** If the f
21960 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69  lags parameter i
21970 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
21980 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66  blob is opened f
21990 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20  or .** read and 
219a0 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 66  write access. If
219b0 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65   it is zero, the
219c0 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20   blob is opened 
219d0 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20 61 63 63  for read .** acc
219e0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75  ess..**.** On su
219f0 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f  ccess, [SQLITE_O
21a00 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  K] is returned a
21a10 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b  nd the new .** [
21a20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
21a30 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73 20 77  lob handle] is w
21a40 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f  ritten to *ppBlo
21a50 62 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20  b..** Otherwise 
21a60 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  an error code is
21a70 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a   returned and .*
21a80 2a 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74  * any value writ
21a90 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73  ten to *ppBlob s
21aa0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
21ab0 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e  d by the caller.
21ac0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
21ad0 6e 20 73 65 74 73 20 74 68 65 20 64 61 74 61 62  n sets the datab
21ae0 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f 72  ase-handle error
21af0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
21b00 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
21b10 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
21b20 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
21b30 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
21b40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
21b50 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69  lob_open(.  sqli
21b60 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68  te3*,.  const ch
21b70 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74  ar *zDb,.  const
21b80 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20   char *zTable,. 
21b90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
21ba0 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lumn,.  sqlite3_
21bb0 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e  int64 iRow,.  in
21bc0 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74  t flags,.  sqlit
21bd0 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62  e3_blob **ppBlob
21be0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
21bf0 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 4c  REF:  Close A BL
21c00 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  OB Handle.**.** 
21c10 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b 73  Close an open [s
21c20 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
21c30 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2f 0a 69  ob handle]..*/.i
21c40 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
21c50 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c  close(sqlite3_bl
21c60 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
21c70 50 49 33 52 45 46 3a 20 20 52 65 74 75 72 6e 20  PI3REF:  Return 
21c80 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f  The Size Of An O
21c90 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 52  pen BLOB.**.** R
21ca0 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 69  eturn the size i
21cb0 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 62  n bytes of the b
21cc0 6c 6f 62 20 61 63 63 65 73 73 69 62 6c 65 20 76  lob accessible v
21cd0 69 61 20 74 68 65 20 6f 70 65 6e 20 0a 2a 2a 20  ia the open .** 
21ce0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
21cf0 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61 73  blob-handle] pas
21d00 73 65 64 20 61 73 20 61 6e 20 61 72 67 75 6d 65  sed as an argume
21d10 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  nt..*/.int sqlit
21d20 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71  e3_blob_bytes(sq
21d30 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
21d40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21d50 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20   Read Data From 
21d60 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
21d70 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ally.**.** This 
21d80 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
21d90 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72   to read data fr
21da0 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b  om an open .** [
21db0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
21dc0 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74 6f  lob-handle] into
21dd0 20 61 20 63 61 6c 6c 65 72 20 73 75 70 70 6c 69   a caller suppli
21de0 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20  ed buffer..** n 
21df0 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
21e00 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75  e copied into bu
21e10 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f 6d 20 74  ffer.** z from t
21e20 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74  he open blob, st
21e30 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74  arting at offset
21e40 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20   iOffset..**.** 
21e50 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49  On success, SQLI
21e60 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
21e70 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  d. Otherwise, an
21e80 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
21e90 4f 52 20 7c 20 53 51 4c 69 74 65 20 65 72 72 6f  OR | SQLite erro
21ea0 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  r code] or an.**
21eb0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
21ec0 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65  EAD | extended e
21ed0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
21ee0 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  turned..*/.int s
21ef0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
21f00 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
21f10 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c   void *z, int n,
21f20 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
21f30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21f40 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f   Write Data Into
21f50 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
21f60 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tally.**.** This
21f70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
21f80 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20  d to write data 
21f90 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a  into an open .**
21fa0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
21fb0 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 66 72   blob-handle] fr
21fc0 6f 6d 20 61 20 75 73 65 72 20 73 75 70 70 6c 69  om a user suppli
21fd0 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20  ed buffer..** n 
21fe0 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
21ff0 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68  e copied from th
22000 65 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69 6e  e buffer.** poin
22010 74 65 64 20 74 6f 20 62 79 20 7a 20 69 6e 74 6f  ted to by z into
22020 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20   the open blob, 
22030 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
22040 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a  et iOffset..**.*
22050 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
22060 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61  3_blob | blob-ha
22070 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20  ndle] passed as 
22080 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
22090 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 70  nt.** was not op
220a0 65 6e 65 64 20 66 6f 72 20 77 72 69 74 69 6e 67  ened for writing
220b0 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 61   (the flags para
220c0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
220d0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a  3_blob_open()].*
220e0 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20 74 68  ** was zero), th
220f0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
22100 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  rns [SQLITE_READ
22110 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ONLY]..**.** Thi
22120 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f  s function may o
22130 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63  nly modify the c
22140 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 62  ontents of the b
22150 6c 6f 62 2c 20 69 74 20 69 73 0a 2a 2a 20 6e 6f  lob, it is.** no
22160 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  t possible to in
22170 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 20  crease the size 
22180 6f 66 20 61 20 62 6c 6f 62 20 75 73 69 6e 67 20  of a blob using 
22190 74 68 69 73 20 41 50 49 2e 20 49 66 0a 2a 2a 20  this API. If.** 
221a0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69  offset iOffset i
221b0 73 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62 79  s less than n by
221c0 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64  tes from the end
221d0 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a 2a   of the blob, .*
221e0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
221f0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
22200 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74   no data is writ
22210 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75  ten..**.** On su
22220 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b  ccess, SQLITE_OK
22230 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74   is returned. Ot
22240 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20  herwise, an .** 
22250 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
22260 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64  SQLite error cod
22270 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  e] or an.** [SQL
22280 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
22290 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20   extended error 
222a0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
222b0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
222c0 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c  3_blob_write(sql
222d0 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e  ite3_blob *, con
222e0 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20  st void *z, int 
222f0 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  n, int iOffset);
22300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22310 3a 20 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20  :  Virtual File 
22320 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a 2a  System Objects.*
22330 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66  *.** A virtual f
22340 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 20  ilesystem (VFS) 
22350 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  is an [sqlite3_v
22360 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68  fs] object.** th
22370 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  at SQLite uses t
22380 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69  o interact.** wi
22390 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  th the underlyin
223a0 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
223b0 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69 6c 64 73  em.  Most builds
223c0 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20   come with a.** 
223d0 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56  single default V
223e0 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72 6f  FS that is appro
223f0 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 68  priate for the h
22400 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a  ost computer..**
22410 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 62   New VFSes can b
22420 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64  e registered and
22430 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 20   existing VFSes 
22440 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65  can be unregiste
22450 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  red..** The foll
22460 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
22470 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a   are provided..*
22480 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
22490 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65  _vfs_find() inte
224a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
224b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53  pointer to a VFS
224c0 20 67 69 76 65 6e 20 69 74 73 0a 2a 2a 20 6e 61   given its.** na
224d0 6d 65 2e 20 20 4e 61 6d 65 73 20 61 72 65 20 63  me.  Names are c
224e0 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 20 20  ase sensitive.  
224f0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  If there is no m
22500 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a 2a 2a 20  atch, a NULL.** 
22510 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
22520 6e 65 64 2e 20 20 49 66 20 7a 56 66 73 4e 61 6d  ned.  If zVfsNam
22530 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  e is NULL then t
22540 68 65 20 64 65 66 61 75 6c 74 20 0a 2a 2a 20 56  he default .** V
22550 46 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  FS is returned. 
22560 20 49 66 20 61 20 76 61 6c 69 64 20 56 46 53 20   If a valid VFS 
22570 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
22580 6e 65 64 2c 20 69 74 73 0a 2a 2a 20 76 66 73 4d  ned, its.** vfsM
22590 75 74 65 78 20 66 69 65 6c 64 20 77 69 6c 6c 20  utex field will 
225a0 68 61 76 65 20 62 65 65 6e 20 69 6e 69 74 69 61  have been initia
225b0 6c 69 7a 65 64 20 61 6e 64 20 6e 52 65 66 20 77  lized and nRef w
225c0 69 6c 6c 20 62 65 0a 2a 2a 20 67 72 65 61 74 65  ill be.** greate
225d0 72 20 74 68 61 6e 20 7a 65 72 6f 2e 20 20 54 68  r than zero.  Th
225e0 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  e sqlite3_vfs_re
225f0 6c 65 61 73 65 28 29 20 66 75 6e 63 74 69 6f 6e  lease() function
22600 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 75 73   should.** be us
22610 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  ed to release th
22620 65 20 56 46 53 20 77 68 65 6e 20 69 74 20 69 73  e VFS when it is
22630 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
22640 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53  d..**.** New VFS
22650 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  es are registere
22660 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76  d with sqlite3_v
22670 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 20 20  fs_register().  
22680 45 61 63 68 0a 2a 2a 20 6e 65 77 20 56 46 53 20  Each.** new VFS 
22690 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
226a0 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
226b0 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
226c0 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65  set..** The same
226d0 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69   VFS can be regi
226e0 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
226f0 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e  times without in
22700 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65  jury..** To make
22710 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53   an existing VFS
22720 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c   into the defaul
22730 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20  t VFS, register 
22740 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68  it again.** with
22750 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
22760 61 67 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 55  ag set..** .** U
22770 6e 72 65 67 69 73 74 65 72 20 61 20 56 46 53 20  nregister a VFS 
22780 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33  with the sqlite3
22790 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
227a0 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  ) interface..** 
227b0 49 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  If the default V
227c0 46 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72  FS is unregister
227d0 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20  ed, another VFS 
227e0 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20  is chosen as.** 
227f0 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68  the default.  Th
22800 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65  e choice for the
22810 20 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69   new VFS is arbi
22820 74 72 61 72 79 2e 0a 2a 2f 0a 73 71 6c 69 74 65  trary..*/.sqlite
22830 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76  3_vfs *sqlite3_v
22840 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68  fs_find(const ch
22850 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69  ar *zVfsName);.i
22860 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  nt sqlite3_vfs_r
22870 65 6c 65 61 73 65 28 73 71 6c 69 74 65 33 5f 76  elease(sqlite3_v
22880 66 73 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  fs*);.int sqlite
22890 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73  3_vfs_register(s
228a0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
228b0 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20   makeDflt);.int 
228c0 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
228d0 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
228e0 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  fs*);../*.** CAP
228f0 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a  I3REF: Mutexes.*
22900 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
22910 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
22920 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72  routines for thr
22930 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69  ead.** synchroni
22940 7a 61 74 69 6f 6e 2e 20 20 54 68 6f 75 67 68 20  zation.  Though 
22950 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65  they are intende
22960 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a  d for internal.*
22970 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c  * use by SQLite,
22980 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73   code that links
22990 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20   against SQLite 
229a0 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20  is.** permitted 
229b0 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68  to use any of th
229c0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
229d0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73  .** The SQLite s
229e0 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61  ource code conta
229f0 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ins multiple imp
22a00 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 0a 2a 2a  lementations .**
22a10 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78 20   of these mutex 
22a20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 63 61  routines that ca
22a30 6e 20 62 65 20 73 65 6c 65 63 74 65 64 20 61 74  n be selected at
22a40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
22a50 20 62 79 20 64 65 66 69 6e 69 6e 67 20 6f 6e 65   by defining one
22a60 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
22a70 67 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  g C preprocessor
22a80 20 6d 61 63 72 6f 73 3a 0a 2a 2a 0a 2a 2a 20 3c   macros:.**.** <
22a90 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  ul>.** <li>   SQ
22aa0 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
22ab0 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  AD.** <li>   SQL
22ac0 49 54 45 5f 4d 55 54 45 58 5f 57 49 4e 33 32 0a  ITE_MUTEX_WIN32.
22ad0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
22ae0 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c  _MUTEX_NOOP.** <
22af0 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
22b00 45 58 5f 41 50 50 44 45 46 0a 2a 2a 20 3c 2f 75  EX_APPDEF.** </u
22b10 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 6e 6f 6e 65  l>.**.** If none
22b20 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 6d 61   of the above ma
22b30 63 72 6f 73 20 69 73 20 64 65 66 69 6e 65 64 2c  cros is defined,
22b40 20 74 68 65 20 63 6f 64 65 20 75 73 65 73 0a 2a   the code uses.*
22b50 2a 20 61 20 64 65 66 61 75 6c 74 20 69 6d 70 6c  * a default impl
22b60 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
22b70 20 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f   .** The SQLITE_
22b80 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65  MUTEX_NOOP imple
22b90 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73  mentation is a s
22ba0 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 0a  et of routines .
22bb0 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20  ** that does no 
22bc0 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64  real locking and
22bd0 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   is appropriate 
22be0 66 6f 72 20 75 73 65 20 69 6e 20 0a 2a 2a 20 61  for use in .** a
22bf0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
22c00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
22c10 20 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 49   .** If the SQLI
22c20 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
22c30 69 73 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  is defined, then
22c40 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70   no mutex.** imp
22c50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69  lementation is i
22c60 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65  ncluded with the
22c70 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 0a 2a   library.  The.*
22c80 2a 20 6d 75 74 65 78 20 69 6e 74 65 72 66 61 63  * mutex interfac
22c90 65 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  e routines defin
22ca0 65 64 20 61 62 6f 76 65 20 61 72 65 20 65 78 74  ed above are ext
22cb0 65 72 6e 61 6c 0a 2a 2a 20 72 65 66 65 72 65 6e  ernal.** referen
22cc0 63 65 73 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ces in the SQLit
22cd0 65 20 6c 69 62 72 61 72 79 20 66 6f 72 20 77 68  e library for wh
22ce0 69 63 68 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ich implementati
22cf0 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 62 65 20 70  ons.** must be p
22d00 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 61  rovided by the a
22d10 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  pplication..**.*
22d20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  * The sqlite3_mu
22d30 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74  tex_alloc() rout
22d40 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20  ine allocates a 
22d50 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64  new.** mutex and
22d60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
22d70 65 72 20 74 6f 20 69 74 2e 20 20 49 66 20 69 74  er to it.  If it
22d80 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a   returns NULL.**
22d90 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74   that means that
22da0 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e   a mutex could n
22db0 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e  ot be allocated.
22dc0 20 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c    SQLite.** will
22dd0 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63   unwind its stac
22de0 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20  k and return an 
22df0 65 72 72 6f 72 2e 20 20 54 68 65 20 61 72 67 75  error.  The argu
22e00 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
22e10 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
22e20 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   is one of these
22e30 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
22e40 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ts:.**.** <ul>.*
22e50 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
22e60 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69  UTEX_FAST.** <li
22e70 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
22e80 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69  RECURSIVE.** <li
22e90 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
22ea0 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a  STATIC_MASTER.**
22eb0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
22ec0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a  TEX_STATIC_MEM.*
22ed0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
22ee0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32  UTEX_STATIC_MEM2
22ef0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
22f00 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52  _MUTEX_STATIC_PR
22f10 4e 47 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  NG.** </ul>.**.*
22f20 2a 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20  * The first two 
22f30 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20  constants cause 
22f40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
22f50 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a  loc() to create.
22f60 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20  ** a new mutex. 
22f70 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69   The new mutex i
22f80 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e  s recursive when
22f90 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
22fa0 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73  CURSIVE.** is us
22fb0 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73  ed but not neces
22fc0 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53  sarily so when S
22fd0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
22fe0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65   is used..** The
22ff0 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
23000 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
23010 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69  eed to make a di
23020 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
23030 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  ween SQLITE_MUTE
23040 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20  X_RECURSIVE and 
23050 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
23060 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20  T if it does.** 
23070 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 42 75  not want to.  Bu
23080 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e  t SQLite will on
23090 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63  ly request a rec
230a0 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a  ursive mutex in.
230b0 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69  ** cases where i
230c0 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f  t really needs o
230d0 6e 65 2e 20 20 49 66 20 61 20 66 61 73 74 65 72  ne.  If a faster
230e0 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d   non-recursive m
230f0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
23100 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  tation is availa
23110 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20  ble on the host 
23120 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75  platform, the mu
23130 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a  tex subsystem.**
23140 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75   might return su
23150 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65  ch a mutex in re
23160 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45  sponse to SQLITE
23170 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a  _MUTEX_FAST..**.
23180 2a 2a 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c  ** The other all
23190 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  owed parameters 
231a0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
231b0 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65  _alloc() each re
231c0 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  turn.** a pointe
231d0 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72  r to a static pr
231e0 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e  eexisting mutex.
231f0 20 20 54 68 72 65 65 20 73 74 61 74 69 63 20 6d    Three static m
23200 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73  utexes are.** us
23210 65 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  ed by the curren
23220 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  t version of SQL
23230 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 72  ite.  Future ver
23240 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
23250 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 74  ** may add addit
23260 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74  ional static mut
23270 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75  exes.  Static mu
23280 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e  texes are for in
23290 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79  ternal.** use by
232a0 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41   SQLite only.  A
232b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
232c0 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65   use SQLite mute
232d0 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73  xes should.** us
232e0 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d  e only the dynam
232f0 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 72  ic mutexes retur
23300 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55  ned by SQLITE_MU
23310 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53  TEX_FAST or.** S
23320 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
23330 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  RSIVE..**.** Not
23340 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66  e that if one of
23350 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   the dynamic mut
23360 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53  ex parameters (S
23370 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
23380 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55  .** or SQLITE_MU
23390 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69  TEX_RECURSIVE) i
233a0 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69  s used then sqli
233b0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
233c0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64  ).** returns a d
233d0 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f  ifferent mutex o
233e0 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 42  n every call.  B
233f0 75 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69  ut for the stati
23400 63 20 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65  c .** mutex type
23410 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65  s, the same mute
23420 78 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e  x is returned on
23430 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74   every call that
23440 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65   has.** the same
23450 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a   type number..**
23460 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
23470 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75  mutex_free() rou
23480 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73  tine deallocates
23490 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a   a previously.**
234a0 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d   allocated dynam
234b0 69 63 20 6d 75 74 65 78 2e 20 20 53 51 4c 69 74  ic mutex.  SQLit
234c0 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20  e is careful to 
234d0 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79  deallocate every
234e0 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  .** dynamic mute
234f0 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61  x that it alloca
23500 74 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69  tes.  The dynami
23510 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e  c mutexes must n
23520 6f 74 20 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65  ot be in .** use
23530 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64   when they are d
23540 65 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74  eallocated.  Att
23550 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c  empting to deall
23560 6f 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a  ocate a static.*
23570 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20  * mutex results 
23580 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
23590 61 76 69 6f 72 2e 20 20 53 51 4c 69 74 65 20 6e  avior.  SQLite n
235a0 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73  ever deallocates
235b0 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74  .** a static mut
235c0 65 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ex..**.** The sq
235d0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
235e0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
235f0 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74  mutex_try() rout
23600 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ines attempt.** 
23610 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78  to enter a mutex
23620 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  .  If another th
23630 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20  read is already 
23640 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78  within the mutex
23650 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  ,.** sqlite3_mut
23660 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20  ex_enter() will 
23670 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65  block and sqlite
23680 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69  3_mutex_try() wi
23690 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ll return.** SQL
236a0 49 54 45 5f 42 55 53 59 2e 20 20 54 68 65 20 73  ITE_BUSY.  The s
236b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
236c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
236d0 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a  urns SQLITE_OK.*
236e0 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75  * upon successfu
236f0 6c 20 65 6e 74 72 79 2e 20 20 4d 75 74 65 78 65  l entry.  Mutexe
23700 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  s created using 
23710 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
23720 55 52 53 49 56 45 20 63 61 6e 0a 2a 2a 20 62 65  URSIVE can.** be
23730 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c   entered multipl
23740 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73  e times by the s
23750 61 6d 65 20 74 68 72 65 61 64 2e 20 20 49 6e 20  ame thread.  In 
23760 73 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a  such cases the,.
23770 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65  ** mutex must be
23780 20 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c   exited an equal
23790 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
237a0 20 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20   before another 
237b0 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e  thread.** can en
237c0 74 65 72 2e 20 20 49 66 20 74 68 65 20 73 61 6d  ter.  If the sam
237d0 65 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74  e thread tries t
237e0 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65  o enter any othe
237f0 72 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 0a  r kind of mutex.
23800 2a 2a 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ** more than onc
23810 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  e, the behavior 
23820 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 20  is undefined.   
23830 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
23840 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63  r exhibit.** suc
23850 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74  h behavior in it
23860 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74  s own use of mut
23870 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  exes..**.** The 
23880 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 78  sqlite3_mutex_ex
23890 69 74 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69  it() routine exi
238a0 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20  ts a mutex that 
238b0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
238c0 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65  y entered by the
238d0 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 54   same thread.  T
238e0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
238f0 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74  s undefined if t
23900 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20  he mutex is not 
23910 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
23920 64 20 6f 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  d or.** is not c
23930 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74  urrently allocat
23940 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  ed.  SQLite will
23950 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72   never do either
23960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23970 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
23980 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
23990 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75  ex_notheld() rou
239a0 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74  tines.** are int
239b0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
239c0 73 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74  side assert() st
239d0 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 79 20  atements.  They 
239e0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
239f0 20 74 72 75 65 20 69 66 20 74 68 65 20 6d 75 74   true if the mut
23a00 65 78 20 69 6e 20 74 68 65 69 72 20 61 72 67 75  ex in their argu
23a10 6d 65 6e 74 20 69 73 20 68 65 6c 64 20 6f 72 20  ment is held or 
23a20 6e 6f 74 20 68 65 6c 64 2c 0a 2a 2a 20 72 65 73  not held,.** res
23a30 70 65 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68  pectively, by th
23a40 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
23a50 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  . The implementa
23a60 74 69 6f 6e 20 69 73 0a 2a 2a 20 6e 6f 74 20 72  tion is.** not r
23a70 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69  equired to provi
23a80 64 65 64 20 77 6f 72 6b 69 6e 67 20 69 6d 70 6c  ded working impl
23a90 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
23aa0 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  hese.** routines
23ab0 20 61 73 20 74 68 65 69 72 20 69 6e 74 65 6e 64   as their intend
23ac0 65 64 20 75 73 65 20 69 73 20 77 69 74 68 69 6e  ed use is within
23ad0 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
23ae0 65 6e 74 73 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 49  ents.** only.  I
23af0 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  f the implementa
23b00 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72  tion does not pr
23b10 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a  ovide working.**
23b20 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65   versions of the
23b30 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20  se routines, it 
23b40 6d 75 73 74 20 61 74 20 6c 65 61 73 74 20 70 72  must at least pr
23b50 6f 76 69 64 65 20 73 74 75 62 73 0a 2a 2a 20 74  ovide stubs.** t
23b60 68 61 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  hat always retur
23b70 6e 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  n true..**.** If
23b80 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
23b90 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
23ba0 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  eld() is a NULL 
23bb0 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20  pointer then.** 
23bc0 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  the routine shou
23bd0 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 54 68  ld return 1.  Th
23be0 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72  is seems counter
23bf0 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65  -intuitive since
23c00 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20  .** clearly the 
23c10 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20  mutex cannot be 
23c20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20  held if it does 
23c30 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20  not exist.  But 
23c40 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f  the.** the reaso
23c50 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73  n the mutex does
23c60 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65   not exist is be
23c70 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20  cause the build 
23c80 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20  is not.** using 
23c90 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65  mutexes.  And we
23ca0 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65   do not want the
23cb0 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69   assert() contai
23cc0 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  ning the.** call
23cd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
23ce0 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c  x_held() to fail
23cf0 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  , so a non-zero 
23d00 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65  return is.** the
23d10 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69   appropriate thi
23d20 6e 67 20 74 6f 20 64 6f 2e 20 20 54 68 65 20 73  ng to do.  The s
23d30 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
23d40 68 65 6c 64 28 29 20 0a 2a 2a 20 69 6e 74 65 72  held() .** inter
23d50 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f  face should also
23d60 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67   return 1 when g
23d70 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  iven a NULL poin
23d80 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ter..*/.sqlite3_
23d90 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d  mutex *sqlite3_m
23da0 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b  utex_alloc(int);
23db0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
23dc0 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33  tex_free(sqlite3
23dd0 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73  _mutex*);.void s
23de0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
23df0 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  er(sqlite3_mutex
23e00 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
23e10 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65  mutex_try(sqlite
23e20 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20  3_mutex*);.void 
23e30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
23e40 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ave(sqlite3_mute
23e50 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  x*);.int sqlite3
23e60 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69  _mutex_held(sqli
23e70 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74  te3_mutex*);.int
23e80 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e   sqlite3_mutex_n
23e90 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d  otheld(sqlite3_m
23ea0 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  utex*);../*.** C
23eb0 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54  API3REF: Mutex T
23ec0 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ypes.**.** The [
23ed0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
23ee0 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65  loc()] interface
23ef0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
23f00 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63  argument.** whic
23f10 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  h is one of thes
23f20 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
23f30 6e 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  nts..*/.#define 
23f40 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
23f50 54 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a  T             0.
23f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
23f70 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 20  UTEX_RECURSIVE  
23f80 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
23f90 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
23fa0 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a  TIC_MASTER    2.
23fb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
23fc0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20  UTEX_STATIC_MEM 
23fd0 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69        3  /* sqli
23fe0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a  te3_malloc() */.
23ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
24000 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32  UTEX_STATIC_MEM2
24010 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
24020 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
24030 72 79 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ry() */.#define 
24040 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
24050 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20  TIC_PRNG      5 
24060 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64   /* sqlite3_rand
24070 6f 6d 28 29 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  om() */.../*.** 
24080 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68  Undo the hack th
24090 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61  at converts floa
240a0 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73  ting point types
240b0 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a   to integer for.
240c0 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f  ** builds on pro
240d0 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20  cessors without 
240e0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
240f0 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65  upport..*/.#ifde
24100 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
24110 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75  OATING_POINT.# u
24120 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64  ndef double.#end
24130 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  if..#ifdef __cpl
24140 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64  usplus.}  /* End
24150 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e 20   of the 'extern 
24160 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65  "C"' block */.#e
24170 6e 64 69 66 0a 23 65 6e 64 69 66 0a              ndif.#endif.