/ Hex Artifact Content
Login

Artifact fb4c95cd6995379741b46ffb6f38c5ed87bc26a9:


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 35 35 20 32 30 30 37 2f  in,v 1.255 2007/
05f0: 30 39 2f 30 33 20 31 35 3a 31 39 3a 33 35 20 64  09/03 15:19:35 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 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
10a0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
10b0: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
10c0: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
10d0: 72 65 74 75 72 6e 73 20 54 52 55 45 20 28 6e 6f  returns TRUE (no
10e0: 6e 7a 65 72 6f 29 20 69 66 20 53 51 4c 69 74 65  nzero) if SQLite
10f0: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1100: 74 68 0a 2a 2a 20 61 6c 6c 20 6f 66 20 69 74 73  th.** all of its
1110: 20 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64   mutexes enabled
1120: 20 61 6e 64 20 69 73 20 74 68 75 73 20 74 68 72   and is thus thr
1130: 65 61 64 73 61 66 65 2e 20 20 49 74 20 72 65 74  eadsafe.  It ret
1140: 75 72 6e 73 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  urns.** zero if 
1150: 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 62  the particular b
1160: 75 69 6c 64 20 69 73 20 66 6f 72 20 73 69 6e 67  uild is for sing
1170: 6c 65 2d 74 68 72 65 61 64 65 64 20 6f 70 65 72  le-threaded oper
1180: 61 74 69 6f 6e 0a 2a 2a 20 6f 6e 6c 79 2e 0a 2a  ation.** only..*
1190: 2a 0a 2a 2a 20 52 65 61 6c 6c 79 20 61 6c 6c 20  *.** Really all 
11a0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 64 6f 65  this routine doe
11b0: 73 20 69 73 20 72 65 74 75 72 6e 20 74 72 75 65  s is return true
11c0: 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63   if SQLite was c
11d0: 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
11e0: 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 54 48 52  the -DSQLITE_THR
11f0: 45 41 44 53 41 46 45 3d 31 20 6f 70 74 69 6f 6e  EADSAFE=1 option
1200: 20 61 6e 64 20 66 61 6c 73 65 20 69 66 0a 2a 2a   and false if.**
1210: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 2d   compiled with -
1220: 44 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  DSQLITE_THREADSA
1230: 46 45 3d 30 2e 20 20 49 66 20 53 51 4c 69 74 65  FE=0.  If SQLite
1240: 20 75 73 65 73 20 61 6e 0a 2a 2a 20 61 70 70 6c   uses an.** appl
1250: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1260: 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 2c  mutex subsystem,
1270: 20 6d 61 6c 6c 6f 63 20 73 75 62 73 79 73 74 65   malloc subsyste
1280: 6d 2c 20 63 6f 6c 6c 61 74 69 6e 67 0a 2a 2a 20  m, collating.** 
1290: 73 65 71 75 65 6e 63 65 2c 20 56 46 53 2c 20 53  sequence, VFS, S
12a0: 51 4c 20 66 75 6e 63 74 69 6f 6e 2c 20 70 72 6f  QL function, pro
12b0: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 2c 20  gress callback, 
12c0: 63 6f 6d 6d 69 74 20 68 6f 6f 6b 2c 0a 2a 2a 20  commit hook,.** 
12d0: 65 78 74 65 6e 73 69 6f 6e 2c 20 6f 72 20 6f 74  extension, or ot
12e0: 68 65 72 20 61 63 63 65 73 73 6f 72 69 65 73 20  her accessories 
12f0: 61 6e 64 20 74 68 65 73 65 20 61 64 64 2d 6f 6e  and these add-on
1300: 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 74 68 72  s are not.** thr
1310: 65 61 64 73 61 66 65 2c 20 74 68 65 6e 20 63 6c  eadsafe, then cl
1320: 65 61 72 6c 79 20 74 68 65 20 63 6f 6d 62 69 6e  early the combin
1330: 61 74 69 6f 6e 20 77 69 6c 6c 20 6e 6f 74 20 62  ation will not b
1340: 65 20 74 68 72 65 61 64 73 61 66 65 0a 2a 2a 20  e threadsafe.** 
1350: 65 69 74 68 65 72 2e 20 20 48 65 6e 63 65 2c 20  either.  Hence, 
1360: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6e 65 76  this routine nev
1370: 65 72 20 72 65 70 6f 72 74 73 20 74 68 61 74 20  er reports that 
1380: 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
1390: 73 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  s guaranteed to 
13a0: 62 65 20 74 68 72 65 61 64 73 61 66 65 2c 20 6f  be threadsafe, o
13b0: 6e 6c 79 20 77 68 65 6e 20 69 74 20 69 73 20 67  nly when it is g
13c0: 75 61 72 61 6e 74 65 65 64 20 6e 6f 74 0a 2a 2a  uaranteed not.**
13d0: 20 74 6f 20 62 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   to be..**.** Th
13e0: 69 73 20 69 73 20 61 6e 20 65 78 70 65 72 69 6d  is is an experim
13f0: 65 6e 74 61 6c 20 41 50 49 20 61 6e 64 20 6d 61  ental API and ma
1400: 79 20 67 6f 20 61 77 61 79 20 6f 72 20 63 68 61  y go away or cha
1410: 6e 67 65 20 69 6e 20 66 75 74 75 72 65 0a 2a 2a  nge in future.**
1420: 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
1430: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
1440: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
1450: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
1460: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1470: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 45 61   Handle.**.** Ea
1480: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
1490: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
14a0: 73 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65  sented by pointe
14b0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14c0: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75   of the.** opaqu
14d0: 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65  e structure name
14e0: 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74  d "sqlite3".  It
14f0: 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68   is useful to th
1500: 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  ink of an sqlite
1510: 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20  3.** pointer as 
1520: 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  an object.  The 
1530: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1540: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1550: 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  6()], and.** [sq
1560: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1570: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
1580: 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  its constructors
1590: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
15a0: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73  _close()] is its
15b0: 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68   destructor.  Th
15c0: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
15d0: 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
15e0: 20 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74   (such as [sqlit
15f0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1600: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
1610: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
1620: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1630: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
1640: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
1650: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
1660: 64 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62  ds on this.** ob
1670: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
1680: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
1690: 73 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a  sqlite3;.../*.**
16a0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
16b0: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a  t Integer Types.
16c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f 6d 70 69  **.** Some compi
16d0: 6c 65 72 73 20 64 6f 20 6e 6f 74 20 73 75 70 70  lers do not supp
16e0: 6f 72 74 20 74 68 65 20 22 6c 6f 6e 67 20 6c 6f  ort the "long lo
16f0: 6e 67 22 20 64 61 74 61 74 79 70 65 2e 20 20 53  ng" datatype.  S
1700: 6f 20 77 65 20 68 61 76 65 0a 2a 2a 20 74 6f 20  o we have.** to 
1710: 64 6f 20 63 6f 6d 70 69 6c 65 72 2d 73 70 65 63  do compiler-spec
1720: 69 66 69 63 20 74 79 70 65 64 65 66 73 20 66 6f  ific typedefs fo
1730: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1740: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1750: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4d 61 6e  egers..**.** Man
1760: 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
1770: 63 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 71  ce functions req
1780: 75 69 72 65 20 61 20 36 34 2d 62 69 74 20 69 6e  uire a 64-bit in
1790: 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 73 2e  teger arguments.
17a0: 0a 2a 2a 20 54 68 6f 73 65 20 69 6e 74 65 72 66  .** Those interf
17b0: 61 63 65 73 20 61 72 65 20 64 65 63 6c 61 72 65  aces are declare
17c0: 64 20 75 73 69 6e 67 20 74 68 69 73 20 74 79 70  d using this typ
17d0: 65 64 65 66 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  edef..*/.#ifdef 
17e0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
17f0: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
1800: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
1810: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1820: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
1830: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
1840: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1850: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
1860: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
1870: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
1880: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
1890: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
18a0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
18b0: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
18c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
18d0: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
18e0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
18f0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
1900: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
1910: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
1920: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
1930: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
1940: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
1950: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
1960: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
1970: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
1980: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
1990: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
19a0: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
19b0: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
19c0: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
19d0: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
19e0: 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65  g-point.*/.#ifde
19f0: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
1a00: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
1a10: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
1a20: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
1a30: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1a40: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
1a50: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1a60: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 68 69 73  .**.** Call this
1a70: 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
1a80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
1a90: 72 75 63 74 75 72 65 20 74 68 61 74 20 77 61 73  ructure that was
1aa0: 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72   previously.** r
1ab0: 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
1ac0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1ad0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ae0: 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
1af0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64  3_open_v2()] and
1b00: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
1b10: 6e 67 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ng database will
1b20: 20 62 79 0a 2a 2a 20 63 6c 6f 73 65 64 2e 0a 2a   by.** closed..*
1b30: 2a 0a 2a 2a 20 41 6c 6c 20 53 51 4c 20 73 74 61  *.** All SQL sta
1b40: 74 65 6d 65 6e 74 73 20 70 72 65 70 61 72 65 64  tements prepared
1b50: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b60: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1b70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1b80: 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6d 75 73  pare16_v2()] mus
1b90: 74 20 62 65 20 64 65 73 74 72 6f 79 65 64 20 75  t be destroyed u
1ba0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1bb0: 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 62 65 66  nalize()].** bef
1bc0: 6f 72 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ore this routine
1bd0: 20 69 73 20 63 61 6c 6c 65 64 2e 20 4f 74 68 65   is called. Othe
1be0: 72 77 69 73 65 2c 20 53 51 4c 49 54 45 5f 42 55  rwise, SQLITE_BU
1bf0: 53 59 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  SY is returned a
1c00: 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  nd the.** databa
1c10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 72 65  se connection re
1c20: 6d 61 69 6e 73 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a  mains open..**.*
1c30: 2a 20 50 61 73 73 69 6e 67 20 74 68 69 73 20 72  * Passing this r
1c40: 6f 75 74 69 6e 65 20 61 20 64 61 74 61 62 61 73  outine a databas
1c50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1c60: 74 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65  t has already be
1c70: 65 6e 0a 2a 2a 20 63 6c 6f 73 65 64 20 72 65 73  en.** closed res
1c80: 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
1c90: 64 20 62 65 68 61 76 69 6f 72 2e 20 20 49 66 20  d behavior.  If 
1ca0: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  other interfaces
1cb0: 20 74 68 61 74 0a 2a 2a 20 72 65 66 65 72 65 6e   that.** referen
1cc0: 63 65 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  ce the same data
1cd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1ce0: 61 72 65 20 70 65 6e 64 69 6e 67 20 28 65 69 74  are pending (eit
1cf0: 68 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 73 61  her in the.** sa
1d00: 6d 65 20 74 68 72 65 61 64 20 6f 72 20 69 6e 20  me thread or in 
1d10: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
1d20: 73 29 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  s) when this rou
1d30: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 0a  tine is called,.
1d40: 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1d50: 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1d60: 64 20 61 6e 64 20 69 73 20 61 6c 6d 6f 73 74 20  d and is almost 
1d70: 63 65 72 74 61 69 6e 6c 79 20 75 6e 64 65 73 69  certainly undesi
1d80: 72 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  rable..*/.int sq
1d90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
1da0: 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  te3 *);../*.** T
1db0: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61  he type for a ca
1dc0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e  llback function.
1dd0: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61  .** This is lega
1de0: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65  cy and deprecate
1df0: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64  d.  It is includ
1e00: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
1e10: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
1e20: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f  ty and is not do
1e30: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70  cumented..*/.typ
1e40: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
1e50: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69  e3_callback)(voi
1e60: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63  d*,int,char**, c
1e70: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  har**);../*.** C
1e80: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65  API3REF: One-Ste
1e90: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f  p Query Executio
1ea0: 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a  n Interface.**.*
1eb0: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1ec0: 20 69 73 20 75 73 65 64 20 74 6f 20 64 6f 20 61   is used to do a
1ed0: 20 6f 6e 65 2d 74 69 6d 65 20 65 76 61 6c 75 61   one-time evalua
1ee0: 74 61 74 69 6f 6e 20 6f 66 20 7a 65 72 6f 0a 2a  tation of zero.*
1ef0: 2a 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74  * or more SQL st
1f00: 61 74 65 6d 65 6e 74 73 2e 20 20 55 54 46 2d 38  atements.  UTF-8
1f10: 20 74 65 78 74 20 6f 66 20 74 68 65 20 53 51 4c   text of the SQL
1f20: 20 73 74 61 74 65 6d 65 6e 74 73 20 74 6f 0a 2a   statements to.*
1f30: 2a 20 62 65 20 65 76 61 6c 75 74 65 64 20 69 73  * be evaluted is
1f40: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
1f50: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1f60: 65 72 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65  er.  The stateme
1f70: 6e 74 73 0a 2a 2a 20 61 72 65 20 70 72 65 70 61  nts.** are prepa
1f80: 72 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75  red one by one u
1f90: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1fa0: 65 70 61 72 65 28 29 5d 2c 20 65 76 61 6c 75 61  epare()], evalua
1fb0: 74 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ted.** using [sq
1fc0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 74  lite3_step()], t
1fd0: 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73  hen destroyed us
1fe0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1ff0: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
2000: 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  If one or more o
2010: 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2020: 65 6e 74 73 20 61 72 65 20 71 75 65 72 69 65 73  ents are queries
2030: 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 61  , then.** the ca
2040: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2050: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2060: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
2070: 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  s.** invoked onc
2080: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f  e for each row o
2090: 66 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75  f the query resu
20a0: 6c 74 2e 20 20 54 68 69 73 20 63 61 6c 6c 62 61  lt.  This callba
20b0: 63 6b 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 72  ck.** should nor
20c0: 6d 61 6c 6c 79 20 72 65 74 75 72 6e 20 30 2e 20  mally return 0. 
20d0: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
20e0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
20f0: 65 72 6f 0a 2a 2a 20 76 61 6c 75 65 20 74 68 65  ero.** value the
2100: 6e 20 74 68 65 20 71 75 65 72 79 20 69 73 20 61  n the query is a
2110: 62 6f 72 74 65 64 2c 20 61 6c 6c 20 73 75 62 73  borted, all subs
2120: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
2130: 6d 65 6e 74 73 0a 2a 2a 20 61 72 65 20 73 6b 69  ments.** are ski
2140: 70 70 65 64 20 61 6e 64 20 74 68 65 20 73 71 6c  pped and the sql
2150: 69 74 65 33 5f 65 78 65 63 28 29 20 66 75 6e 63  ite3_exec() func
2160: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
2170: 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
2180: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  .**.** The 4th p
2190: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 69 73  arameter to this
21a0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 6e   interface is an
21b0: 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
21c0: 65 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 61  er that is.** pa
21d0: 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
21e0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
21f0: 63 74 69 6f 6e 20 61 73 20 69 74 73 20 66 69 72  ction as its fir
2200: 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
2210: 0a 2a 2a 20 54 68 65 20 32 6e 64 20 70 61 72 61  .** The 2nd para
2220: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
2230: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69  lback function i
2240: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
2250: 2a 2a 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  ** columns in th
2260: 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 2e 20  e query result. 
2270: 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
2280: 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
2290: 63 6b 0a 2a 2a 20 69 73 20 61 6e 20 61 72 72 61  ck.** is an arra
22a0: 79 20 6f 66 20 73 74 72 69 6e 67 73 20 68 6f 6c  y of strings hol
22b0: 64 69 6e 67 20 74 68 65 20 76 61 6c 75 65 73 20  ding the values 
22c0: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 0a  for each column.
22d0: 2a 2a 20 61 73 20 65 78 74 72 61 63 74 65 64 20  ** as extracted 
22e0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
22f0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
2300: 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
2310: 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
2320: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
2330: 6f 66 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 62  of strings.** ob
2340: 74 61 69 6e 65 64 20 75 73 69 6e 67 20 5b 73 71  tained using [sq
2350: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2360: 65 28 29 5d 20 61 6e 64 20 68 6f 6c 64 69 6e 67  e()] and holding
2370: 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  .** the names of
2380: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   each column..**
2390: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
23a0: 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
23b0: 20 4e 55 4c 4c 2c 20 65 76 65 6e 20 66 6f 72 20   NULL, even for 
23c0: 71 75 65 72 69 65 73 2e 20 20 41 20 4e 55 4c 4c  queries.  A NULL
23d0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
23e0: 6e 6f 74 20 61 6e 20 65 72 72 6f 72 2e 20 20 49  not an error.  I
23f0: 74 20 6a 75 73 74 20 6d 65 61 6e 73 20 74 68 61  t just means tha
2400: 74 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  t no callback.**
2410: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
2420: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72  ..**.** If an er
2430: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65  ror occurs while
2440: 20 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c   parsing or eval
2450: 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 28  uating the SQL (
2460: 62 75 74 0a 2a 2a 20 6e 6f 74 20 77 68 69 6c 65  but.** not while
2470: 20 65 78 65 63 75 74 69 6e 67 20 74 68 65 20 63   executing the c
2480: 61 6c 6c 62 61 63 6b 29 20 74 68 65 6e 20 61 6e  allback) then an
2490: 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
24a0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
24b0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
24c0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
24d0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
24e0: 6f 63 28 29 5d 20 61 6e 64 0a 2a 2a 20 2a 65 72  oc()] and.** *er
24f0: 72 6d 73 67 20 69 73 20 6d 61 64 65 20 74 6f 20  rmsg is made to 
2500: 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 6d 65  point to that me
2510: 73 73 61 67 65 2e 20 20 54 68 65 20 63 61 6c 6c  ssage.  The call
2520: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ing function.** 
2530: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
2540: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
2550: 65 6d 6f 72 79 20 75 73 69 6e 67 20 5b 73 71 6c  emory using [sql
2560: 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2570: 20 49 66 20 65 72 72 6d 73 67 3d 3d 4e 55 4c 4c   If errmsg==NULL
2580: 2c 20 74 68 65 6e 20 6e 6f 20 65 72 72 6f 72 20  , then no error 
2590: 6d 65 73 73 61 67 65 20 69 73 20 65 76 65 72 20  message is ever 
25a0: 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54  written..**.** T
25b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
25c0: 69 73 20 69 73 20 53 51 4c 49 54 45 5f 4f 4b 20  is is SQLITE_OK 
25d0: 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  if there are no 
25e0: 65 72 72 6f 72 73 20 61 6e 64 0a 2a 2a 20 73 6f  errors and.** so
25f0: 6d 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45  me other [SQLITE
2600: 5f 4f 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64  _OK | return cod
2610: 65 5d 20 69 66 20 74 68 65 72 65 20 69 73 20 61  e] if there is a
2620: 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 20 54 68  n error.  .** Th
2630: 65 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 74  e particular ret
2640: 75 72 6e 20 76 61 6c 75 65 20 64 65 70 65 6e 64  urn value depend
2650: 73 20 6f 6e 20 74 68 65 20 74 79 70 65 20 6f 66  s on the type of
2660: 20 65 72 72 6f 72 2e 20 0a 2a 2a 0a 2a 2f 0a 69   error. .**.*/.i
2670: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
2680: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
2690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26b0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
26c0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26d0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
26e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26f0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
2700: 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69 6e 74  valuted */.  int
2710: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
2720: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
2730: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
2740: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
2750: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
2760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2770: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2780: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
2790: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
27a0: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
27b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
27d0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
27e0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
27f0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2800: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
2810: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a  DS: SQLITE_OK.**
2820: 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20  .** Many SQLite 
2830: 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2840: 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75   an integer resu
2850: 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65  lt code from the
2860: 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 61 62   set shown.** ab
2870: 6f 76 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ove in order to 
2880: 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73  indicates succes
2890: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
28a0: 0a 2a 2a 20 54 68 65 20 72 65 73 75 6c 74 20 63  .** The result c
28b0: 6f 64 65 73 20 61 62 6f 76 65 20 61 72 65 20 74  odes above are t
28c0: 68 65 20 6f 6e 6c 79 20 6f 6e 65 73 20 72 65 74  he only ones ret
28d0: 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
28e0: 69 6e 20 69 74 73 0a 2a 2a 20 64 65 66 61 75 6c  in its.** defaul
28f0: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2e  t configuration.
2900: 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 5b    However, the [
2910: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
2920: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
2930: 0a 2a 2a 20 41 50 49 20 63 61 6e 20 62 65 20 75  .** API can be u
2940: 73 65 64 20 74 6f 20 73 65 74 20 61 20 64 61 74  sed to set a dat
2950: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 6f 69 6e  abase connectoin
2960: 20 74 6f 20 72 65 74 75 72 6e 20 6d 6f 72 65 20   to return more 
2970: 64 65 74 61 69 6c 65 64 0a 2a 2a 20 72 65 73 75  detailed.** resu
2980: 6c 74 20 63 6f 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  lt codes..**.** 
2990: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
29a0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
29b0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29c0: 6f 64 65 73 5d 0a 2a 2a 0a 2a 2f 0a 23 64 65 66  odes].**.*/.#def
29d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
29e0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
29f0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
2a00: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
2a10: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
2a20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2a30: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
2a40: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
2a50: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
2a60: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
2a70: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
2a80: 20 20 20 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53     2   /* NOT US
2a90: 45 44 2e 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67  ED. Internal log
2aa0: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
2ab0: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
2ac0: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
2ad0: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
2ae0: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
2af0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
2b00: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
2b10: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
2b20: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
2b30: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
2b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
2b50: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
2b60: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
2b70: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
2b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b90: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
2ba0: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
2bb0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
2bc0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
2bd0: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
2be0: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
2bf0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
2c00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c10: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
2c20: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
2c30: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
2c40: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
2c50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
2c60: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
2c70: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
2c80: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
2c90: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
2ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
2cb0: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
2cc0: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
2cd0: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
2ce0: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
2cf0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
2d00: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
2d10: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
2d20: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
2d30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2d40: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
2d50: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
2d60: 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20  Table or record 
2d70: 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65  not found */.#de
2d80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
2d90: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
2da0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
2db0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
2dc0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
2dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
2de0: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
2df0: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
2e00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2e10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2e20: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
2e30: 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e  5   /* NOT USED.
2e40: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
2e50: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
2e60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e70: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
2e80: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
2e90: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
2ea0: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
2eb0: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
2ec0: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
2ed0: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
2ee0: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
2ef0: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
2f00: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
2f10: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
2f20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2f30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
2f40: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
2f50: 74 6f 20 63 6f 6e 74 72 61 69 6e 74 20 76 69 6f  to contraint vio
2f60: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
2f70: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
2f80: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
2f90: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
2fa0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2fb0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
2fc0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
2fd0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
2fe0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2ff0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
3000: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
3010: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
3020: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
3030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
3040: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
3050: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
3060: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
3070: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
3080: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
3090: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
30a0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
30b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
30c0: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
30d0: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
30e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
30f0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
3100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3110: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
3120: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
3130: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
3140: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
3150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
3160: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
3170: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
3180: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
3190: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
31a0: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
31b0: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
31c0: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
31d0: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
31e0: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
31f0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
3200: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3210: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
3220: 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  Codes.**.** In i
3230: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
3240: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
3250: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
3260: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69  turn one of 26 i
3270: 6e 74 65 67 65 72 0a 2a 2a 20 72 65 73 75 6c 74  nteger.** result
3280: 20 63 6f 64 65 73 20 64 65 73 63 72 69 62 65 64   codes described
3290: 20 61 74 20 72 65 73 75 6c 74 2d 63 6f 64 65 73   at result-codes
32a0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
32b0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
32c0: 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66   that.** many of
32d0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
32e0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 72  des are too cour
32f0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
3300: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
3310: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
3320: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
3330: 6f 62 6c 65 6d 73 20 61 73 20 75 73 65 72 73 20  oblems as users 
3340: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
3350: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
3360: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
3370: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
3380: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
3390: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
33a0: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
33b0: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
33c0: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
33d0: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
33e0: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
33f0: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
3400: 65 72 72 6f 72 73 2e 20 20 54 68 65 20 65 78 74  errors.  The ext
3410: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
3420: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 28  es are enabled (
3430: 6f 72 20 64 69 73 61 62 6c 65 64 29 20 66 6f 72  or disabled) for
3440: 20 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61   .** each databa
3450: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
3460: 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
3470: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
3480: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
3490: 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f 66  ..** .** Some of
34a0: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65   the available e
34b0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
34c0: 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20  odes are listed 
34d0: 61 62 6f 76 65 2e 0a 2a 2a 20 57 65 20 65 78 70  above..** We exp
34e0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
34f0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
3500: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
3510: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
3520: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
3530: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
3540: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
3550: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
3560: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
3570: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
3580: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
3590: 4c 69 74 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  Lite..** .** The
35a0: 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66   symbolic name f
35b0: 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72  or an extended r
35c0: 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61 79  esult code alway
35d0: 73 20 63 6f 6e 74 61 69 6e 73 20 61 20 72 65 6c  s contains a rel
35e0: 61 74 65 64 0a 2a 2a 20 70 72 69 6d 61 72 79 20  ated.** primary 
35f0: 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61  result code as a
3600: 20 70 72 65 66 69 78 2e 20 20 50 72 69 6d 61 72   prefix.  Primar
3610: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63  y result codes c
3620: 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 0a  ontain a single.
3630: 2a 2a 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  ** "_" character
3640: 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65 73 75  .  Extended resu
3650: 6c 74 20 63 6f 64 65 73 20 63 6f 6e 74 61 69 6e  lt codes contain
3660: 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22   two or more "_"
3670: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
3680: 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  The numeric valu
3690: 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64  e of an extended
36a0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63 61 6e   result code can
36b0: 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
36c0: 20 69 74 73 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   its.** correspo
36d0: 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65  nding primary re
36e0: 73 75 6c 74 20 63 6f 64 65 20 62 79 20 6d 61 73  sult code by mas
36f0: 6b 69 6e 67 20 6f 66 66 20 74 68 65 20 6c 6f 77  king off the low
3700: 65 72 20 38 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a  er 8 bytes..**.*
3710: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
3720: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
3730: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
3740: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
3750: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
3760: 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69  y zero..*/.#defi
3770: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
3780: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 28 53  READ          (S
3790: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
37a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
37b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
37c0: 5f 52 45 41 44 20 20 20 20 28 53 51 4c 49 54 45  _READ    (SQLITE
37d0: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
37e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37f0: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
3800: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3810: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
3820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3830: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
3840: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3850: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
3860: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
3870: 46 53 59 4e 43 20 20 20 20 20 28 53 51 4c 49 54  FSYNC     (SQLIT
3880: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
3890: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
38a0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
38b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
38c0: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
38d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
38e0: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
38f0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3900: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
3910: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
3920: 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  OCK        (SQLI
3930: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
3940: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3950: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
3960: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3970: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
3980: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3990: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
39a0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
39b0: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
39c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
39d0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 28 53 51  LOCKED       (SQ
39e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
39f0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
3a00: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
3a10: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
3a20: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 43 6f 6d 62  tions.**.** Comb
3a30: 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66  ination of the f
3a40: 6f 6c 6c 6f 77 69 6e 67 20 62 69 74 20 76 61 6c  ollowing bit val
3a50: 75 65 73 20 61 72 65 20 75 73 65 64 20 61 73 20  ues are used as 
3a60: 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  the.** third arg
3a70: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
3a80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3a90: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
3aa0: 2a 20 61 73 20 66 6f 75 72 74 68 20 61 72 67 75  * as fourth argu
3ab0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 78 4f 70 65  ment to the xOpe
3ac0: 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a  n method of the.
3ad0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
3ae0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2f 0a 23   object..**.*/.#
3af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3b00: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
3b10: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
3b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3b30: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
3b40: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
3b50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3b60: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
3b70: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
3b80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3b90: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
3ba0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
3bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3bc0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
3bd0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
3be0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3bf0: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
3c00: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
3c10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3c20: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
3c30: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
3c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3c50: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
3c60: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
3c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3c80: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
3c90: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 23      0x00000800.#
3ca0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3cb0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
3cc0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23      0x00001000.#
3cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3ce0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
3cf0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23      0x00002000.#
3d00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3d10: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
3d20: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 0a  L   0x00004000..
3d30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3d40: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
3d50: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65  istics.**.** The
3d60: 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69   xDeviceCapabili
3d70: 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ties method of t
3d80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
3d90: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
3da0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
3db0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
3dc0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 66 6f  vector of the fo
3dd0: 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 62 69 74 20 76  llowing.** bit v
3de0: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
3df0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
3e00: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
3e10: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
3e20: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
3e30: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
3e40: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
3e50: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
3e60: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
3e70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3e80: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
3e90: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
3ea0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
3eb0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
3ec0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
3ed0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
3ee0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
3ef0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
3f00: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
3f10: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
3f20: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
3f30: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
3f40: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
3f50: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
3f60: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
3f70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
3f80: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
3f90: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
3fa0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
3fb0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
3fc0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
3fd0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
3fe0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
3ff0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
4000: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
4010: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
4020: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
4030: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
4040: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
4050: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
4060: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
4070: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
4080: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
4090: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
40a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
40b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
40c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
40d0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
40e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
40f0: 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  2       0x000000
4100: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
4110: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
4120: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4130: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
4140: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
4150: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4160: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
4170: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
4180: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4190: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
41a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
41b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
41c0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
41d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
41e0: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  K       0x000000
41f0: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
4200: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
4210: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  K       0x000000
4220: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
4230: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
4240: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31  K       0x000001
4250: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4260: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
4270: 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32  END     0x000002
4280: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4290: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
42a0: 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34  AL      0x000004
42b0: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
42c0: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
42d0: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51   Levels.**.** SQ
42e0: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
42f0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69   the following i
4300: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
4310: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
4320: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
4330: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
4340: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
4350: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
4360: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
4370: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
4380: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
4390: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
43a0: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
43b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
43c0: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
43d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
43e0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
43f0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
4400: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
4410: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
4420: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
4430: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
4440: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
4450: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
4460: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
4470: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
4480: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
4490: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
44a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
44b0: 2a 2a 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  ** object it use
44c0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
44d0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
44e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
44f0: 61 73 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  as.** the second
4500: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
4510: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
4520: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
4530: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
4540: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
4550: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
4560: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
4570: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
4580: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
4590: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
45a0: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
45b0: 73 68 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  shed.  The SQLIT
45c0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 6d 65  E_SYNC_NORMAL me
45d0: 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 6e  ans .** to use n
45e0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
45f0: 6d 61 6e 74 69 63 73 2e 20 20 54 68 65 20 53 51  mantics.  The SQ
4600: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
4610: 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f  lag means .** to
4620: 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73 74   use Mac OS-X st
4630: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
4640: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
4650: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4660: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
4670: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
4680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
4690: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
46a0: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
46b0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
46c0: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
46d0: 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  0.../*.** CAPI3R
46e0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
46f0: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
4700: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
4710: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
4720: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
4730: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
4740: 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  OS.** interface 
4750: 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69 64 75  layer.  Individu
4760: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  al OS interface 
4770: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
4780: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
4790: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
47a0: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
47b0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
47c0: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
47d0: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
47e0: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
47f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
4800: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
4810: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
4820: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
4830: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
4840: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
4850: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
4860: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
4870: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
4880: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
4890: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
48a0: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
48b0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
48c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
48d0: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
48e0: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
48f0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
4900: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
4910: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
4920: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
4930: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
4940: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
4950: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
4960: 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63  ] xOpen method c
4970: 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69 6e 74 65  ontains a pointe
4980: 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61  r to.** an insta
4990: 6e 63 65 20 6f 66 20 74 68 65 20 74 68 69 73 20  nce of the this 
49a0: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
49b0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
49c0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65 64  .** methods used
49d0: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
49e0: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ous operations a
49f0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
4a00: 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  file..**.** The 
4a10: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
4a20: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
4a30: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
4a40: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
4a50: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
4a60: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
4a70: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
4a80: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 20  rmal fsync()..* 
4a90: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
4aa0: 63 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d 58  ce is an.** OS-X
4ab0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
4ac0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e    The SQLITE_SYN
4ad0: 43 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 79 20  C_DATA flag may 
4ae0: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a 2a 2a  be ORed in to.**
4af0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
4b00: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
4b10: 74 68 65 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74  the file and not
4b20: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
4b30: 20 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 65 64   to be.** synced
4b40: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 6e 74  ..** .** The int
4b50: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
4b60: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
4b70: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
4b80: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
4b90: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
4ba0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
4bb0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 41 44 5d 2c 0a  ITE_LOCK_READ],.
4bc0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
4bd0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a  LOCK_RESERVED],.
4be0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
4bf0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
4c00: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
4c10: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
4c20: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78  ]..** </ul>.** x
4c30: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73  Lock() increases
4c40: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f   the lock. xUnlo
4c50: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74  ck() decreases t
4c60: 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 20 54 68  he lock.  .** Th
4c70: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
4c80: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 6c 6f  Lock() method lo
4c90: 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  oks.** to see if
4ca0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
4cb0: 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 74 68 65 72  nnection, either
4cc0: 20 69 6e 20 74 68 69 73 0a 2a 2a 20 70 72 6f 63   in this.** proc
4cd0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
4ce0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
4cf0: 20 68 6f 6c 64 69 6e 67 20 61 6e 20 52 45 53 45   holding an RESE
4d00: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
4d10: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
4d20: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
4d30: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
4d40: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
4d50: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
4d60: 61 6c 73 65 20 69 66 20 6e 6f 74 2e 0a 2a 2a 20  alse if not..** 
4d70: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
4d80: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
4d90: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
4da0: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
4db0: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
4dc0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
4dd0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
4de0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
4df0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
4e00: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4e10: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
4e20: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
4e30: 22 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73  " argument.** is
4e40: 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 70 63 6f   an integer opco
4e50: 64 65 2e 20 20 20 54 68 65 20 74 68 69 72 64 0a  de.   The third.
4e60: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
4e70: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
4e80: 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 6e 64   which is intend
4e90: 65 64 20 74 6f 20 62 65 20 61 20 70 6f 69 6e 74  ed to be a point
4ea0: 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74 72 75 63  er.** to a struc
4eb0: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
4ec0: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
4ed0: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
4ee0: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
4ef0: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
4f00: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
4f10: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
4f20: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
4f30: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
4f40: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
4f50: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
4f60: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
4f70: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
4f80: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
4f90: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
4fa0: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
4fb0: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
4fc0: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
4fd0: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
4fe0: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
4ff0: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
5000: 72 76 65 73 20 6f 70 63 6f 64 65 73 20 6c 65 73  rves opcodes les
5010: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
5020: 74 73 20 6f 77 6e 20 75 73 65 2e 20 0a 2a 2a 20  ts own use. .** 
5030: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
5040: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
5050: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
5060: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
5070: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
5080: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
5090: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
50a0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
50b0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
50c0: 6f 64 65 73 20 0a 2a 2a 20 67 72 65 61 74 65 72  odes .** greater
50d0: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
50e0: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a  id conflicts..**
50f0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
5100: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
5110: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
5120: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
5130: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
5140: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
5150: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
5160: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
5170: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
5180: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
5190: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
51a0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
51b0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
51c0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
51d0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
51e0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
51f0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
5200: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
5210: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
5220: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
5230: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
5240: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5250: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
5260: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5270: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
5280: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5290: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
52a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
52b0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
52c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
52d0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
52e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
52f0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
5300: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5310: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
5320: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5330: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
5340: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
5350: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
5360: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
5370: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
5380: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
5390: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
53a0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
53b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
53c0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
53d0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
53e0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
53f0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5400: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5410: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5420: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5430: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5440: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5450: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5460: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5470: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5480: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5490: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
54a0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
54b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
54c0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
54d0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
54e0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
54f0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5500: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5510: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5520: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5530: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5540: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5550: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5560: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5570: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5580: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5590: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
55a0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
55b0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
55c0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
55d0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
55e0: 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
55f0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
5600: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
5610: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
5620: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
5630: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
5640: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
5650: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
5660: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
5670: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
5680: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
5690: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 5f 69  t iAmt, sqlite_i
56a0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
56b0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
56c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
56d0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
56e0: 74 2c 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  t, sqlite_int64 
56f0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
5700: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
5710: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
5720: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
5730: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
5740: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
5750: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
5760: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
5770: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
5780: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
5790: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
57a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
57b0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
57c0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
57d0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
57e0: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
57f0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
5800: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  le*);.  int (*xF
5810: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
5820: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
5830: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
5840: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
5850: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
5860: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
5870: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
5880: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
5890: 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69  e*);.  /* Additi
58a0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
58b0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
58c0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
58d0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
58e0: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
58f0: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
5900: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  s.**.** These in
5910: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
5920: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
5930: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
5940: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
5950: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
5960: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
5970: 64 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  d to the [sqlite
5980: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
5990: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
59a0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
59b0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
59c0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
59d0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
59e0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
59f0: 20 63 61 73 65 73 20 74 68 65 20 78 46 69 6c 65   cases the xFile
5a00: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
5a10: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
5a20: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
5a30: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
5a40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
5a50: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
5a60: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
5a70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
5a80: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
5a90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
5aa0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
5ab0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
5ac0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
5ad0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
5ae0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 20 54  nt points to.  T
5af0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
5b00: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
5b10: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
5b20: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
5b30: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
5b40: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
5b50: 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69  efined..*/.#defi
5b60: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
5b70: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
5b80: 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   1../*.** CAPI3R
5b90: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
5ba0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
5bb0: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
5bc0: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
5bd0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
5be0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
5bf0: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
5c00: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
5c10: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
5c20: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
5c30: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
5c40: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
5c50: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
5c60: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
5c70: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
5c80: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
5c90: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
5ca0: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
5cb0: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
5cc0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
5cd0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
5ce0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
5cf0: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
5d00: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
5d10: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
5d20: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
5d30: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
5d40: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
5d50: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
5d60: 66 61 63 65 20 62 65 74 77 65 65 6e 20 74 68 65  face between the
5d70: 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20  .** SQLite core 
5d80: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
5d90: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
5da0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
5db0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
5dc0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
5dd0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
5de0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a   file system"..*
5df0: 2a 0a 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f  *.** The iVersio
5e00: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
5e10: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
5e20: 65 20 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74  e larger for fut
5e30: 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
5e40: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
5e50: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
5e60: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
5e70: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
5e80: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
5e90: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
5ea0: 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
5eb0: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
5ec0: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
5ed0: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
5ee0: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
5ef0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
5f00: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
5f10: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
5f20: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
5f30: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
5f40: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
5f50: 20 52 65 67 69 73 74 65 72 65 64 20 76 66 73 20   Registered vfs 
5f60: 6d 6f 64 75 6c 65 73 20 61 72 65 20 6b 65 70 74  modules are kept
5f70: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
5f80: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
5f90: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
5fa0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
5fb0: 72 65 67 69 73 74 65 72 5f 76 66 73 28 29 5d 0a  register_vfs()].
5fc0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
5fd0: 75 6e 72 65 67 69 73 74 65 72 5f 76 66 73 28 29  unregister_vfs()
5fe0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
5ff0: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
6000: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
6010: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
6020: 69 74 65 33 5f 66 69 6e 64 5f 76 66 73 28 29 5d  ite3_find_vfs()]
6030: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
6040: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
6050: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
6060: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
6070: 6c 79 20 66 69 65 6c 64 73 20 69 6e 20 74 68 65  ly fields in the
6080: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a   sqlite3_vfs .**
6090: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
60a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
60b0: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
60c0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
60d0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
60e0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
60f0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
6100: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
6110: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
6120: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
6130: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
6140: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
6150: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
6160: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
6170: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
6180: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
6190: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
61a0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
61b0: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
61c0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
61d0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
61e0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
61f0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  les..**.** SQLit
6200: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
6210: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
6220: 61 6d 65 20 73 74 72 69 6e 67 20 70 61 73 73 65  ame string passe
6230: 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20  d to.** xOpen() 
6240: 69 73 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61  is a full pathna
6250: 6d 65 20 61 73 20 67 65 6e 65 72 61 74 65 64 20  me as generated 
6260: 62 79 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  by xFullPathname
6270: 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74  () and.** that t
6280: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
6290: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
62a0: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
62b0: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
62c0: 64 2e 20 20 53 6f 20 74 68 65 20 5b 73 71 6c 69  d.  So the [sqli
62d0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74  te3_file] can st
62e0: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
62f0: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
6300: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
6310: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
6320: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
6330: 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eason..**.** The
6340: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
6350: 74 6f 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20  to xOpen() is a 
6360: 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6c 61 67  copy of the flag
6370: 73 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  s argument.** to
6380: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
6390: 32 28 29 5d 2e 20 20 49 66 20 5b 73 71 6c 69 74  2()].  If [sqlit
63a0: 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73  e3_open()] or [s
63b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
63c0: 0a 2a 2a 20 69 73 20 75 73 65 64 2c 20 74 68 65  .** is used, the
63d0: 6e 20 66 6c 61 67 73 20 69 73 20 5b 53 51 4c 49  n flags is [SQLI
63e0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
63f0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
6400: 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 20 49 66  N_CREATE]..** If
6410: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
6420: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
6430: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
6440: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
6450: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
6460: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
6470: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
6480: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a  utFlags may be.*
6490: 2a 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 53 51  * set..** .** SQ
64a0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
64b0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
64c0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
64d0: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
64e0: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
64f0: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
6500: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a  ing opened:.** .
6510: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6520: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
6530: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
6540: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
6550: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
6560: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
6570: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
6580: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
6590: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
65a0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
65b0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
65c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
65d0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
65e0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
65f0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
6600: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75  _JOURNAL].** </u
6610: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  l>.**.** The fil
6620: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
6630: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
6640: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
6650: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73  gs to.** changes
6660: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
6670: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
6680: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
6690: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
66a0: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
66b0: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
66c0: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
66d0: 6b 2c 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  k, might make.**
66e0: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
66f0: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
6700: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
6710: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72 65  this journal are
6720: 0a 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70  .** also a no-op
6730: 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  .  Any attempt t
6740: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
6750: 61 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  al return SQLITE
6760: 5f 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 68  _IOERR..** Or th
6770: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
6780: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
6790: 20 74 68 65 20 61 20 64 61 74 61 62 61 73 65 20   the a database 
67a0: 66 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  file will.** be 
67b0: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
67c0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
67d0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
67e0: 72 61 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20  random order.** 
67f0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
6800: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
6810: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a  ordingly..** .**
6820: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
6830: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
6840: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
6850: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  s to the xOpen.*
6860: 2a 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a  * method:.** .**
6870: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
6880: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
6890: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
68a0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
68b0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
68c0: 6c 3e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 5b 53  l>.** .** The [S
68d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
68e0: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
68f0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
6900: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
6910: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
6920: 6f 73 65 64 2e 20 20 54 68 69 73 20 77 69 6c 6c  osed.  This will
6930: 20 61 6c 77 61 79 73 20 62 65 20 73 65 74 20 66   always be set f
6940: 6f 72 20 54 45 4d 50 20 0a 2a 2a 20 64 61 74 61  or TEMP .** data
6950: 62 61 73 65 73 20 61 6e 64 20 6a 6f 75 72 6e 61  bases and journa
6960: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f  ls and for subjo
6970: 75 72 6e 61 6c 73 2e 20 20 54 68 65 20 0a 2a 2a  urnals.  The .**
6980: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
6990: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65  CLUSIVE] flag me
69a0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
69b0: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a  uld be opened.**
69c0: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
69d0: 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61  ccess.  This fla
69e0: 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c  g is set for all
69f0: 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a   files except.**
6a00: 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61   for the main da
6a10: 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20  tabase file..** 
6a20: 0a 2a 2a 20 53 70 61 63 65 20 74 6f 20 68 6f 6c  .** Space to hol
6a30: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
6a40: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
6a50: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
6a60: 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ird .** argument
6a70: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 6c 6c   to xOpen is all
6a80: 6f 63 61 74 65 64 20 62 79 20 63 61 6c 6c 65 72  ocated by caller
6a90: 20 28 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72   (the SQLite cor
6aa0: 65 29 2e 20 0a 2a 2a 20 73 7a 4f 73 46 69 6c 65  e). .** szOsFile
6ab0: 20 62 79 74 65 73 20 61 72 65 20 61 6c 6c 6f 63   bytes are alloc
6ac0: 61 74 65 64 20 66 6f 72 20 74 68 69 73 20 6f 62  ated for this ob
6ad0: 6a 65 63 74 2e 20 20 54 68 65 20 78 4f 70 65 6e  ject.  The xOpen
6ae0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 66 69 6c 6c 73   method.** fills
6af0: 20 69 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   in the allocate
6b00: 64 20 73 70 61 63 65 2e 0a 2a 2a 20 0a 2a 2a 20  d space..** .** 
6b10: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
6b20: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
6b30: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
6b40: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 20 0a 2a  CCESS_EXISTS] .*
6b50: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
6b60: 65 20 65 78 69 73 74 61 6e 63 65 20 6f 66 20 61  e existance of a
6b70: 20 66 69 6c 65 2c 0a 2a 2a 20 6f 72 20 5b 53 51   file,.** or [SQ
6b80: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
6b90: 57 52 49 54 45 5d 20 74 6f 20 74 65 73 74 20 74  WRITE] to test t
6ba0: 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61 20 66 69  o see.** if a fi
6bb0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
6bc0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
6bd0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
6be0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
6bf0: 74 6f 20 73 65 65 20 69 66 20 61 20 66 69 6c 65  to see if a file
6c00: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
6c10: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 69 6c 65  dable.  The file
6c20: 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69   can be a .** di
6c30: 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20  rectory..** .** 
6c40: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
6c50: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
6c60: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
6c70: 31 20 62 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68  1 byte for.** th
6c80: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 73  e output buffers
6c90: 20 66 6f 72 20 78 47 65 74 54 65 6d 70 4e 61 6d   for xGetTempNam
6ca0: 65 20 61 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e  e and xFullPathn
6cb0: 61 6d 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  ame..** .** The 
6cc0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
6cd0: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75  Sleep(), and xCu
6ce0: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65  rrentTime() inte
6cf0: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
6d00: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
6d10: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
6d20: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
6d30: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
6d40: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
6d50: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
6d60: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
6d70: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
6d80: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
6d90: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
6da0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
6db0: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
6dc0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
6dd0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
6de0: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
6df0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
6e00: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
6e10: 61 69 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78  ained.  The.** x
6e20: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
6e30: 61 75 73 65 20 74 68 65 20 63 61 6c 6c 69 6e 67  ause the calling
6e40: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
6e50: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
6e60: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
6e70: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
6e80: 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74  n.  The xCurrent
6e90: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
6ea0: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
6eb0: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
6ec0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
6ed0: 65 20 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a  e and.** time..*
6ee0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
6ef0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
6f00: 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74  ite3_vfs;.struct
6f10: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
6f20: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
6f30: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
6f40: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
6f50: 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73  umber */.  int s
6f60: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
6f70: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
6f80: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
6f90: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
6fa0: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
6fb0: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
6fc0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
6fd0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
6fe0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
6ff0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
7000: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
7010: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
7020: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
7030: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
7040: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
7050: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
7060: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
7070: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
7080: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
7090: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
70a0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
70b0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
70c0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
70d0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
70e0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
70f0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
7100: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
7110: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
7120: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
7130: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
7140: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
7150: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
7160: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
7170: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
7180: 6e 74 20 28 2a 78 47 65 74 54 65 6d 70 4e 61 6d  nt (*xGetTempNam
7190: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
71a0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
71b0: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
71c0: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
71d0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
71e0: 4e 61 6d 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Name, char *zOut
71f0: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
7200: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
7210: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
7220: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
7230: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
7240: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
7250: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
7260: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a  rrMsg);.  void *
7270: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
7280: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
7290: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
72a0: 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  l);.  void (*xDl
72b0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
72c0: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
72d0: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
72e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
72f0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
7300: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
7310: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
7320: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
7330: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
7340: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
7350: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
7360: 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20  ble*);.  /* New 
7370: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
7380: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
7390: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
73a0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
73b0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
73c0: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
73d0: 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a   happens. */.};.
73e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
73f0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
7400: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
7410: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
7420: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
7430: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
7440: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
7450: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
7460: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
7470: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
7480: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
7490: 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 6b  termine.** the k
74a0: 69 6e 64 20 6f 66 20 77 68 61 74 20 6b 69 6e 64  ind of what kind
74b0: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
74c0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
74d0: 6f 64 20 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67  od is.** looking
74e0: 20 66 6f 72 2e 20 20 57 69 74 68 20 53 51 4c 49   for.  With SQLI
74f0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
7500: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
7510: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
7520: 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20  hecks to see if 
7530: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
7540: 20 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43    With SQLITE_AC
7550: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 0a  CESS_READWRITE,.
7560: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
7570: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 74 6f 20  ethod checks to 
7580: 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20  see if the file 
7590: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
75a0: 0a 2a 2a 20 61 6e 64 20 77 72 69 74 61 62 6c 65  .** and writable
75b0: 2e 20 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  .  With SQLITE_A
75c0: 43 43 45 53 53 5f 52 45 41 44 20 74 68 65 20 78  CCESS_READ the x
75d0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
75e0: 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69   checks to see i
75f0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  f the file is re
7600: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69  adable..*/.#defi
7610: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
7620: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
7630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
7640: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23  SS_READWRITE 1.#
7650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
7660: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
7670: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7680: 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
7690: 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
76a0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ult Codes.**.** 
76b0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
76c0: 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
76d0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
76e0: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
76f0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
7700: 65 73 5d 20 66 65 61 74 75 72 65 2e 0a 2a 2a 20  es] feature..** 
7710: 42 79 20 64 65 66 61 75 6c 74 2c 20 53 51 4c 69  By default, SQLi
7720: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
7730: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 6f 6e  return one of on
7740: 6c 79 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a  ly 26 integer.**
7750: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
7760: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 57 68  sult codes].  Wh
7770: 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
7780: 6c 74 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20  lt codes.** are 
7790: 65 6e 61 62 6c 65 64 20 62 79 20 74 68 69 73 20  enabled by this 
77a0: 72 6f 75 74 69 6e 65 2c 20 74 68 65 20 72 65 70  routine, the rep
77b0: 65 74 6f 69 72 65 20 6f 66 20 72 65 73 75 6c 74  etoire of result
77c0: 20 63 6f 64 65 73 20 63 61 6e 20 62 65 0a 2a 2a   codes can be.**
77d0: 20 6d 75 63 68 20 6c 61 72 67 65 72 20 61 6e 64   much larger and
77e0: 20 63 61 6e 20 28 68 6f 70 65 66 75 6c 6c 79 29   can (hopefully)
77f0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
7800: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
7810: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  on.** about the 
7820: 63 61 75 73 65 20 6f 66 20 61 6e 20 65 72 72 6f  cause of an erro
7830: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  r..**.** The sec
7840: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
7850: 61 20 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65 20  a boolean value 
7860: 74 68 61 74 20 74 75 72 6e 73 20 65 78 74 65 6e  that turns exten
7870: 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
7880: 64 65 73 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 20  des on and off. 
7890: 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   Extended result
78a0: 20 63 6f 64 65 73 20 61 72 65 20 6f 66 66 20 62   codes are off b
78b0: 79 20 64 65 66 61 75 6c 74 20 66 6f 72 0a 2a 2a  y default for.**
78c0: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
78d0: 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
78e0: 64 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  der versions of 
78f0: 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
7900: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
7910: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
7920: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
7930: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
7940: 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
7950: 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 45 61 63 68  Rowid.**.** Each
7960: 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
7970: 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
7980: 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
7990: 67 6e 65 64 20 69 6e 74 65 67 65 72 20 6b 65 79  gned integer key
79a0: 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 68 65 20 22  .** called the "
79b0: 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69  rowid". The rowi
79c0: 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
79d0: 6c 61 62 6c 65 20 61 73 20 61 6e 20 75 6e 64 65  lable as an unde
79e0: 63 6c 61 72 65 64 0a 2a 2a 20 63 6f 6c 75 6d 6e  clared.** column
79f0: 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
7a00: 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 2e 20 20  D, or _ROWID_.  
7a10: 49 66 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  If the table has
7a20: 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 0a 2a 2a 20   a column of.** 
7a30: 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49  type INTEGER PRI
7a40: 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68  MARY KEY then th
7a50: 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 61 6e 6f  at column is ano
7a60: 74 68 65 72 20 61 6e 20 61 6c 69 61 73 20 66 6f  ther an alias fo
7a70: 72 20 74 68 65 0a 2a 2a 20 72 6f 77 69 64 2e 0a  r the.** rowid..
7a80: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
7a90: 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 72  ne returns the r
7aa0: 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74  owid of the most
7ab0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 20 69   recent INSERT i
7ac0: 6e 74 6f 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  nto.** the datab
7ad0: 61 73 65 20 66 72 6f 6d 20 74 68 65 20 64 61 74  ase from the dat
7ae0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7af0: 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 66 69   given in the fi
7b00: 72 73 74 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  rst .** argument
7b10: 2e 20 20 49 66 20 6e 6f 20 69 6e 73 65 72 74 73  .  If no inserts
7b20: 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
7b30: 72 65 64 20 6f 6e 20 74 68 69 73 20 64 61 74 61  red on this data
7b40: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
7b50: 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
7b60: 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  rned..**.** If a
7b70: 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20  n INSERT occurs 
7b80: 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
7b90: 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64  , then the rowid
7ba0: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65 72   of the.** inser
7bb0: 74 65 64 20 72 6f 77 20 69 73 20 72 65 74 75 72  ted row is retur
7bc0: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
7bd0: 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
7be0: 68 65 20 74 72 69 67 67 65 72 0a 2a 2a 20 69 73  he trigger.** is
7bf0: 20 72 75 6e 6e 69 6e 67 2e 20 20 42 75 74 20 6f   running.  But o
7c00: 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
7c10: 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20  terminates, the 
7c20: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
7c30: 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
7c40: 65 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65  e reverts to the
7c50: 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65   last value inse
7c60: 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 0a  rted before the.
7c70: 2a 2a 20 74 72 69 67 67 65 72 20 66 69 72 65 64  ** trigger fired
7c80: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
7c90: 65 72 20 74 68 72 65 61 64 20 64 6f 65 73 20 61  er thread does a
7ca0: 20 6e 65 77 20 69 6e 73 65 72 74 20 6f 6e 20 74   new insert on t
7cb0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
7cc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
7cd0: 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
7ce0: 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  e is running and
7cf0: 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
7d00: 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
7d10: 77 69 64 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  wid,.** then the
7d20: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
7d30: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
7d40: 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 73   undefined..*/.s
7d50: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
7d60: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
7d70: 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
7d80: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7d90: 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
7da0: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
7db0: 66 69 65 64 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  fied.**.** This 
7dc0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
7dd0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
7de0: 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
7df0: 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
7e00: 2a 20 28 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  * (or inserted o
7e10: 72 20 64 65 6c 65 74 65 64 29 20 62 79 20 74 68  r deleted) by th
7e20: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 53 51  e most recent SQ
7e30: 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4f 6e  L statement.  On
7e40: 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68  ly.** changes th
7e50: 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20  at are directly 
7e60: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
7e70: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
7e80: 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74   or.** DELETE st
7e90: 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
7ea0: 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
7eb0: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
7ec0: 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72  y.** triggers ar
7ed0: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20  e not counted.  
7ee0: 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
7ef0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
7f00: 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f  ] function.** to
7f10: 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20   find the total 
7f20: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
7f30: 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  s including chan
7f40: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
7f50: 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 57 69  iggers..**.** Wi
7f60: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
7f70: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 20   a trigger, the 
7f80: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
7f90: 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
7fa0: 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 6f 20  be.** called to 
7fb0: 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
7fc0: 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
7fd0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
7fe0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
7ff0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
8000: 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
8010: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
8020: 6f 64 79 20 6f 66 20 74 68 65 20 74 72 69 67 67  ody of the trigg
8030: 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 63 68  er..**.** All ch
8040: 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
8050: 64 2c 20 65 76 65 6e 20 69 66 20 74 68 65 79 20  d, even if they 
8060: 77 65 72 65 20 6c 61 74 65 72 20 75 6e 64 6f 6e  were later undon
8070: 65 20 62 79 20 61 0a 2a 2a 20 52 4f 4c 4c 42 41  e by a.** ROLLBA
8080: 43 4b 20 6f 72 20 41 42 4f 52 54 2e 20 20 45 78  CK or ABORT.  Ex
8090: 63 65 70 74 2c 20 63 68 61 6e 67 65 73 20 61 73  cept, changes as
80a0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 72  sociated with cr
80b0: 65 61 74 69 6e 67 20 61 6e 64 0a 2a 2a 20 64 72  eating and.** dr
80c0: 6f 70 70 69 6e 67 20 74 61 62 6c 65 73 20 61 72  opping tables ar
80d0: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
80e0: 2a 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 62 61  *.** If a callba
80f0: 63 6b 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69  ck invokes [sqli
8100: 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
8110: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
8120: 72 65 63 75 72 73 69 76 65 6c 79 2c 0a 2a 2a 20  recursively,.** 
8130: 74 68 65 6e 20 74 68 65 20 63 68 61 6e 67 65 73  then the changes
8140: 20 69 6e 20 74 68 65 20 69 6e 6e 65 72 2c 20 72   in the inner, r
8150: 65 63 75 72 73 69 76 65 20 63 61 6c 6c 20 61 72  ecursive call ar
8160: 65 20 63 6f 75 6e 74 65 64 20 74 6f 67 65 74 68  e counted togeth
8170: 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 63  er.** with the c
8180: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6f 75  hanges in the ou
8190: 74 65 72 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  ter call..**.** 
81a0: 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
81b0: 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44  s the command "D
81c0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
81d0: 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52  " without a WHER
81e0: 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64  E clause.** by d
81f0: 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72  ropping and recr
8200: 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65  eating the table
8210: 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68  .  (This is much
8220: 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69   faster than goi
8230: 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e  ng.** through an
8240: 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76  d deleting indiv
8250: 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66  idual elements f
8260: 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20  rom the table.) 
8270: 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74   Because of.** t
8280: 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  his optimization
8290: 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75  , the change cou
82a0: 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46  nt for "DELETE F
82b0: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20  ROM table" will 
82c0: 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72  be.** zero regar
82d0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d  dless of the num
82e0: 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20  ber of elements 
82f0: 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e  that were origin
8300: 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74  ally in the.** t
8310: 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20  able. To get an 
8320: 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
8330: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
8340: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
8350: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
8360: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
8370: 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20   instead..**.** 
8380: 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
8390: 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
83a0: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
83b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
83c0: 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  ** while this ro
83d0: 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
83e0: 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
83f0: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72   value of this r
8400: 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64  outine.** is und
8410: 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
8420: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
8430: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
8440: 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
8450: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
8460: 4d 6f 64 69 66 69 65 64 0a 2a 2a 2a 0a 2a 2a 20  Modified.***.** 
8470: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
8480: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
8490: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
84a0: 73 20 74 68 61 74 20 68 61 76 65 20 62 65 65 6e  s that have been
84b0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 62 79 20  .** modified by 
84c0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
84d0: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
84e0: 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 64 61  nts since the da
84f0: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 0a 2a 2a  tabase handle.**
8500: 20 77 61 73 20 6f 70 65 6e 65 64 2e 20 54 68 69   was opened. Thi
8510: 73 20 69 6e 63 6c 75 64 65 73 20 55 50 44 41 54  s includes UPDAT
8520: 45 2c 20 49 4e 53 45 52 54 20 61 6e 64 20 44 45  E, INSERT and DE
8530: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
8540: 65 78 65 63 75 74 65 64 0a 2a 2a 20 61 73 20 70  executed.** as p
8550: 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
8560: 72 6f 67 72 61 6d 73 2e 20 41 6c 6c 20 63 68 61  rograms. All cha
8570: 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
8580: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 0a   as soon as the.
8590: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
85a0: 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
85b0: 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
85c0: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
85d0: 6e 64 6c 65 20 69 73 0a 2a 2a 20 70 61 73 73 65  ndle is.** passe
85e0: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
85f0: 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
8600: 65 33 5f 66 69 6e 61 6c 69 73 65 28 29 5d 29 2e  e3_finalise()]).
8610: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
8620: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
8630: 6e 67 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  nge()] interface
8640: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
8650: 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f  mplements the co
8660: 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52  mmand "DELETE FR
8670: 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75  OM table" withou
8680: 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65  t a WHERE clause
8690: 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20  .** by dropping 
86a0: 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74  and recreating t
86b0: 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73  he table.  (This
86c0: 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20   is much faster 
86d0: 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68  than going.** th
86e0: 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69  rough and deleti
86f0: 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c  ng individual el
8700: 65 6d 65 6e 74 73 20 66 6f 72 6d 20 74 68 65 20  ements form the 
8710: 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65  table.)  Because
8720: 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69   of.** this opti
8730: 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68  mization, the ch
8740: 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22  ange count for "
8750: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
8760: 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65  e" will be.** ze
8770: 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ro regardless of
8780: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
8790: 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72  lements that wer
87a0: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20  e originally in 
87b0: 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f  the.** table. To
87c0: 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65   get an accurate
87d0: 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75   count of the nu
87e0: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c  mber of rows del
87f0: 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45  eted, use.** "DE
8800: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20  LETE FROM table 
8810: 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64  WHERE 1" instead
8820: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
8830: 65 72 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  er thread makes 
8840: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
8850: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
8860: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
8870: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
8880: 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
8890: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
88a0: 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  f this routine.*
88b0: 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
88c0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
88d0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
88e0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
88f0: 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
8900: 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
8910: 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68  g Query.**.** Th
8920: 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
8930: 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
8940: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
8950: 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
8960: 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
8970: 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
8980: 6e 69 74 79 2e 20 20 54 68 69 73 20 72 6f 75 74  nity.  This rout
8990: 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
89a0: 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
89b0: 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
89c0: 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
89d0: 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
89e0: 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
89f0: 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
8a00: 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
8a10: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
8a20: 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
8a30: 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73  y..**.** It is s
8a40: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
8a50: 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
8a60: 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
8a70: 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
8a80: 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
8a90: 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
8aa0: 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
8ab0: 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
8ac0: 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
8ad0: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
8ae0: 65 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  e with a databas
8af0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
8b00: 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
8b10: 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
8b20: 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
8b30: 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
8b40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 20  ..**.** The SQL 
8b50: 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
8b60: 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
8b70: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
8b80: 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
8b90: 20 49 66 20 61 6e 20 69 6e 74 65 72 72 75 70 74   If an interrupt
8ba0: 65 64 20 6f 70 65 72 61 74 69 6f 6e 20 77 61 73  ed operation was
8bb0: 20 61 6e 20 75 70 64 61 74 65 20 74 68 61 74 20   an update that 
8bc0: 69 73 20 69 6e 73 69 64 65 20 61 6e 0a 2a 2a 20  is inside an.** 
8bd0: 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
8be0: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
8bf0: 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
8c00: 6e 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  n will be rolled
8c10: 0a 2a 2a 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  .** back automat
8c20: 69 63 61 6c 6c 79 2e 0a 2a 2f 0a 76 6f 69 64 20  ically..*/.void 
8c30: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
8c40: 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
8c50: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
8c60: 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
8c70: 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
8c80: 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
8c90: 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
8ca0: 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65  turn true if the
8cb0: 20 67 69 76 65 6e 20 69 6e 70 75 74 20 73 74 72   given input str
8cc0: 69 6e 67 20 63 6f 6d 70 72 69 73 65 73 0a 2a 2a  ing comprises.**
8cd0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d   one or more com
8ce0: 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
8cf0: 65 6e 74 73 2e 20 46 6f 72 20 74 68 65 20 73 71  ents. For the sq
8d00: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
8d10: 20 63 61 6c 6c 2c 0a 2a 2a 20 74 68 65 20 70 61   call,.** the pa
8d20: 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
8d30: 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
8d40: 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 20 46   UTF-8 string. F
8d50: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
8d60: 6d 70 6c 65 74 65 31 36 28 29 2c 20 61 20 6e 75  mplete16(), a nu
8d70: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 6d 61 63  l-terminated mac
8d80: 68 69 6e 65 20 62 79 74 65 20 6f 72 64 65 72 20  hine byte order 
8d90: 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
8da0: 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
8db0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
8dc0: 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  es are useful fo
8dd0: 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  r command-line i
8de0: 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
8df0: 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
8e00: 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
8e10: 78 74 20 66 6f 72 6d 73 20 6f 6e 65 20 6f 72 20  xt forms one or 
8e20: 6d 6f 72 65 20 63 6f 6d 70 6c 65 74 65 20 53 51  more complete SQ
8e30: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 0a  L statements or.
8e40: 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
8e50: 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
8e60: 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
8e70: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 69  the statements i
8e80: 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
8e90: 72 20 70 61 72 73 69 6e 67 2e 20 54 68 65 20 61  r parsing. The a
8ea0: 6c 67 6f 72 69 74 68 6d 20 69 73 20 73 69 6d 70  lgorithm is simp
8eb0: 6c 65 2e 20 20 49 66 20 74 68 65 20 0a 2a 2a 20  le.  If the .** 
8ec0: 6c 61 73 74 20 74 6f 6b 65 6e 20 6f 74 68 65 72  last token other
8ed0: 20 74 68 61 6e 20 73 70 61 63 65 73 20 61 6e 64   than spaces and
8ee0: 20 63 6f 6d 6d 65 6e 74 73 20 69 73 20 61 20 73   comments is a s
8ef0: 65 6d 69 63 6f 6c 6f 6e 2c 20 74 68 65 6e 20 72  emicolon, then r
8f00: 65 74 75 72 6e 20 0a 2a 2a 20 74 72 75 65 2e 20  eturn .** true. 
8f10: 20 41 63 74 75 61 6c 6c 79 2c 20 74 68 65 20 61   Actually, the a
8f20: 6c 67 6f 72 69 74 68 6d 20 69 73 20 61 20 6c 69  lgorithm is a li
8f30: 74 74 6c 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69  ttle more compli
8f40: 63 61 74 65 64 20 74 68 61 6e 20 74 68 61 74 0a  cated than that.
8f50: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64  ** in order to d
8f60: 65 61 6c 20 77 69 74 68 20 74 72 69 67 67 65 72  eal with trigger
8f70: 73 2c 20 62 75 74 20 74 68 65 20 62 61 73 69 63  s, but the basic
8f80: 20 69 64 65 61 20 69 73 20 74 68 65 20 73 61 6d   idea is the sam
8f90: 65 3a 20 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  e:  the.** state
8fa0: 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 6f 6d 70  ment is not comp
8fb0: 6c 65 74 65 20 75 6e 6c 65 73 73 20 69 74 20 65  lete unless it e
8fc0: 6e 64 73 20 69 6e 20 61 20 73 65 6d 69 63 6f 6c  nds in a semicol
8fd0: 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  on..*/.int sqlit
8fe0: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
8ff0: 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
9000: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
9010: 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
9020: 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
9030: 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
9040: 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
9050: 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
9060: 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 54  Y Errors.**.** T
9070: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 64 65 6e  his routine iden
9080: 74 69 66 69 65 73 20 61 20 63 61 6c 6c 62 61 63  tifies a callbac
9090: 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
90a0: 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
90b0: 0a 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 6e 20  .** whenever an 
90c0: 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
90d0: 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
90e0: 73 65 20 74 61 62 6c 65 20 0a 2a 2a 20 74 68 61  se table .** tha
90f0: 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
9100: 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
9110: 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66 20 74 68  locked..** If th
9120: 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
9130: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
9140: 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 28  QLITE_BUSY].** (
9150: 6f 72 20 73 6f 6d 65 74 69 6d 65 73 20 5b 53 51  or sometimes [SQ
9160: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
9170: 45 44 5d 29 0a 2a 2a 20 69 73 20 72 65 74 75 72  ED]).** is retur
9180: 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
9190: 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
91a0: 67 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49  g the lock..** I
91b0: 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
91c0: 61 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ack is not NULL,
91d0: 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c   then the.** cal
91e0: 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e  lback will be in
91f0: 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
9200: 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a  rguments.  The.*
9210: 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  * first argument
9220: 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20   to the handler 
9230: 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
9240: 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
9250: 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
9260: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
9270: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20   this routine.  
9280: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
9290: 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61  ent to.** the ha
92a0: 6e 64 6c 65 72 20 69 73 20 74 68 65 20 6e 75 6d  ndler is the num
92b0: 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
92c0: 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
92d0: 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
92e0: 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
92f0: 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 49  locking event. I
9300: 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
9310: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
9320: 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
9330: 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
9340: 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
9350: 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
9360: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
9370: 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
9380: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
9390: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
93a0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
93b0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
93c0: 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
93d0: 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
93e0: 70 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  pen the.** datab
93f0: 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
9400: 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
9410: 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
9420: 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
9430: 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
9440: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
9450: 68 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62  hat.** it will b
9460: 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  e invoked when t
9470: 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
9480: 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53  tention..** If S
9490: 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
94a0: 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
94b0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
94c0: 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a  could result in.
94d0: 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  ** a deadlock, i
94e0: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  t will return [S
94f0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 6e 73 74  QLITE_BUSY] inst
9500: 65 61 64 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ead..** Consider
9510: 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
9520: 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
9530: 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
9540: 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
9550: 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
9560: 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
9570: 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
9580: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
9590: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
95a0: 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
95b0: 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
95c0: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
95d0: 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
95e0: 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
95f0: 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
9600: 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
9610: 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
9620: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
9630: 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
9640: 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
9650: 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
9660: 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
9670: 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
9680: 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
9690: 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
96a0: 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
96b0: 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
96c0: 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
96d0: 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
96e0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
96f0: 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
9700: 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
9710: 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
9720: 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
9730: 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
9740: 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
9750: 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
9760: 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
9770: 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
9780: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
9790: 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
97a0: 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
97b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
97c0: 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
97d0: 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
97e0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 77  IOERR_BLOCKED] w
97f0: 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  hen.** SQLite is
9800: 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
9810: 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
9820: 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
9830: 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
9840: 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
9850: 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
9860: 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
9870: 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
9880: 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
9890: 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
98a0: 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
98b0: 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
98c0: 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
98d0: 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
98e0: 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
98f0: 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
9900: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
9910: 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
9920: 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
9930: 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66  .** readers.  If
9940: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
9950: 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
9960: 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
9970: 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
9980: 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
9990: 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
99a0: 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
99b0: 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
99c0: 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
99d0: 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
99e0: 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
99f0: 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
9a00: 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
9a10: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
9a20: 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64    This error cod
9a30: 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66  e promotion.** f
9a40: 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74  orces an automat
9a50: 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74  ic rollback of t
9a60: 68 65 20 63 68 61 6e 67 65 73 2e 20 53 65 65 20  he changes. See 
9a70: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
9a80: 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74  http://www.sqlit
9a90: 65 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f 77 69  e.org/cvstrac/wi
9aa0: 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
9ab0: 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
9ac0: 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
9ad0: 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
9ae0: 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
9af0: 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
9b00: 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
9b10: 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
9b20: 2a 2a 09 0a 2a 2a 20 53 71 6c 69 74 65 20 69 73  **..** Sqlite is
9b30: 20 72 65 2d 65 6e 74 72 61 6e 74 2c 20 73 6f 20   re-entrant, so 
9b40: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
9b50: 20 6d 61 79 20 73 74 61 72 74 20 61 20 6e 65 77   may start a new
9b60: 20 71 75 65 72 79 2e 20 0a 2a 2a 20 28 49 74 20   query. .** (It 
9b70: 69 73 20 6e 6f 74 20 63 6c 65 61 72 20 77 68 79  is not clear why
9b80: 20 61 6e 79 6f 6e 65 20 77 6f 75 6c 64 20 65 76   anyone would ev
9b90: 65 72 79 20 77 61 6e 74 20 74 6f 20 64 6f 20 74  ery want to do t
9ba0: 68 69 73 2c 20 62 75 74 20 69 74 0a 2a 2a 20 69  his, but it.** i
9bb0: 73 20 61 6c 6c 6f 77 65 64 2c 20 69 6e 20 74 68  s allowed, in th
9bc0: 65 6f 72 79 2e 29 20 20 42 75 74 20 74 68 65 20  eory.)  But the 
9bd0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79  busy handler may
9be0: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 0a 2a   not close the.*
9bf0: 2a 20 64 61 74 61 62 61 73 65 2e 20 20 43 6c 6f  * database.  Clo
9c00: 73 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  sing the databas
9c10: 65 20 66 72 6f 6d 20 61 20 62 75 73 79 20 68 61  e from a busy ha
9c20: 6e 64 6c 65 72 20 77 69 6c 6c 20 64 65 6c 65 74  ndler will delet
9c30: 65 20 0a 2a 2a 20 64 61 74 61 20 73 74 72 75 63  e .** data struc
9c40: 74 75 72 65 73 20 6f 75 74 20 66 72 6f 6d 20 75  tures out from u
9c50: 6e 64 65 72 20 74 68 65 20 65 78 65 63 75 74 69  nder the executi
9c60: 6e 67 20 71 75 65 72 79 20 61 6e 64 20 77 69 6c  ng query and wil
9c70: 6c 20 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72  l .** probably r
9c80: 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
9c90: 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
9ca0: 20 6f 74 68 65 72 20 72 75 6e 74 69 6d 65 20 65   other runtime e
9cb0: 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  rror..**.** Ther
9cc0: 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
9cd0: 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
9ce0: 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
9cf0: 65 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a  each database.**
9d00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9d10: 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
9d20: 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
9d30: 61 6e 79 20 70 72 65 76 69 6f 75 73 20 6f 6e 65  any previous one
9d40: 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 63  ..** Note that c
9d50: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
9d60: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
9d70: 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
9d80: 20 63 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62 75   clear.** the bu
9d90: 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
9da0: 2a 20 57 68 65 6e 20 6f 70 65 72 61 74 69 6e 67  * When operating
9db0: 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61   in [sqlite3_ena
9dc0: 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
9dd0: 20 7c 20 73 68 61 72 65 64 20 63 61 63 68 65 20   | shared cache 
9de0: 6d 6f 64 65 5d 2c 0a 2a 2a 20 6f 6e 6c 79 20 61  mode],.** only a
9df0: 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
9e00: 64 6c 65 72 20 63 61 6e 20 62 65 20 64 65 66 69  dler can be defi
9e10: 6e 65 64 20 66 6f 72 20 65 61 63 68 20 64 61 74  ned for each dat
9e20: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 53  abase file..** S
9e30: 6f 20 69 66 20 74 77 6f 20 64 61 74 61 62 61 73  o if two databas
9e40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 73 68  e connections sh
9e50: 61 72 65 20 61 20 73 69 6e 67 6c 65 20 63 61 63  are a single cac
9e60: 68 65 2c 20 74 68 65 6e 20 63 68 61 6e 67 69 6e  he, then changin
9e70: 67 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  g.** the busy ha
9e80: 6e 64 6c 65 72 20 6f 6e 20 6f 6e 65 20 63 6f 6e  ndler on one con
9e90: 6e 65 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 73  nection will als
9ea0: 6f 20 63 68 61 6e 67 65 20 74 68 65 20 62 75 73  o change the bus
9eb0: 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 6e 20  y.** handler in 
9ec0: 74 68 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63  the other connec
9ed0: 74 69 6f 6e 2e 20 20 54 68 65 20 62 75 73 79 20  tion.  The busy 
9ee0: 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b  handler is invok
9ef0: 65 64 0a 2a 2a 20 69 6e 20 74 68 65 20 74 68 72  ed.** in the thr
9f00: 65 61 64 20 74 68 61 74 20 77 61 73 20 72 75 6e  ead that was run
9f10: 6e 69 6e 67 20 77 68 65 6e 20 74 68 65 20 53 51  ning when the SQ
9f20: 4c 49 54 45 5f 42 55 53 59 20 77 61 73 20 68 69  LITE_BUSY was hi
9f30: 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
9f40: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
9f50: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
9f60: 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
9f70: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
9f80: 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
9f90: 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 54 68  Timeout.**.** Th
9fa0: 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
9fb0: 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 74  a busy handler t
9fc0: 68 61 74 20 73 6c 65 65 70 73 20 66 6f 72 20 61  hat sleeps for a
9fd0: 20 77 68 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a   while when a.**
9fe0: 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
9ff0: 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 20 77  .  The handler w
a000: 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
a010: 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a  le times until .
a020: 2a 2a 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  ** at least "ms"
a030: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
a040: 20 73 6c 65 65 70 69 6e 67 20 68 61 76 65 20 62   sleeping have b
a050: 65 65 6e 20 64 6f 6e 65 2e 20 20 41 66 74 65 72  een done.  After
a060: 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  .** "ms" millise
a070: 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
a080: 67 2c 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  g, the handler r
a090: 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 0a 2a  eturns 0 which.*
a0a0: 2a 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  * causes [sqlite
a0b0: 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
a0c0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
a0d0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
a0e0: 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
a0f0: 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  ** Calling this 
a100: 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
a110: 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
a120: 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
a130: 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
a140: 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
a150: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  rs..**.** There 
a160: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
a170: 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
a180: 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
a190: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
a1a0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20 61  onnection.  If a
a1b0: 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
a1c0: 6c 65 72 20 77 61 73 20 64 65 66 69 6e 65 64 20  ler was defined 
a1d0: 20 0a 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c   .** (using [sql
a1e0: 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
a1f0: 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
a200: 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
a210: 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
a220: 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
a230: 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2f 0a 69  is cleared..*/.i
a240: 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
a250: 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
a260: 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
a270: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
a280: 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
a290: 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
a2a0: 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
a2b0: 6e 65 78 74 20 72 6f 75 74 69 6e 65 20 69 73 20  next routine is 
a2c0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
a2d0: 61 70 70 65 72 20 61 72 6f 75 6e 64 20 5b 73 71  apper around [sq
a2e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a  lite3_exec()]..*
a2f0: 2a 20 49 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  * Instead of inv
a300: 6f 6b 69 6e 67 20 61 20 75 73 65 72 2d 73 75 70  oking a user-sup
a310: 70 6c 69 65 64 20 63 61 6c 6c 62 61 63 6b 20 66  plied callback f
a320: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74  or each row of t
a330: 68 65 0a 2a 2a 20 72 65 73 75 6c 74 2c 20 74 68  he.** result, th
a340: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 6d 65 6d  is routine remem
a350: 62 65 72 73 20 65 61 63 68 20 72 6f 77 20 6f 66  bers each row of
a360: 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 6d   the result in m
a370: 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65  emory.** obtaine
a380: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
a390: 6d 61 6c 6c 6f 63 28 29 5d 2c 20 74 68 65 6e 20  malloc()], then 
a3a0: 72 65 74 75 72 6e 73 20 61 6c 6c 20 6f 66 20 74  returns all of t
a3b0: 68 65 20 72 65 73 75 6c 74 20 61 66 74 65 72 20  he result after 
a3c0: 74 68 65 0a 2a 2a 20 71 75 65 72 79 20 68 61 73  the.** query has
a3d0: 20 66 69 6e 69 73 68 65 64 2e 20 0a 2a 2a 0a 2a   finished. .**.*
a3e0: 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c  * As an example,
a3f0: 20 73 75 70 70 6f 73 65 20 74 68 65 20 71 75 65   suppose the que
a400: 72 79 20 72 65 73 75 6c 74 20 77 68 65 72 65 20  ry result where 
a410: 74 68 69 73 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a  this table:.**.*
a420: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
a430: 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
a440: 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
a450: 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
a460: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
a470: 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
a480: 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
a490: 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
a4a0: 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
a4b0: 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
a4c0: 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
a4d0: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
a4e0: 49 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  If the 3rd argum
a4f0: 65 6e 74 20 77 65 72 65 20 26 61 7a 52 65 73 75  ent were &azResu
a500: 6c 74 20 74 68 65 6e 20 61 66 74 65 72 20 74 68  lt then after th
a510: 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
a520: 6e 73 0a 2a 2a 20 61 7a 52 65 73 75 6c 74 20 77  ns.** azResult w
a530: 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  ill contain the 
a540: 66 6f 6c 6c 6f 77 69 6e 67 20 64 61 74 61 3a 0a  following data:.
a550: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
a560: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
a570: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
a580: 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
a590: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
a5a0: 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
a5b0: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
a5c0: 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
a5d0: 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
a5e0: 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
a5f0: 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
a600: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
a610: 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
a620: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
a630: 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
a640: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
a650: 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
a660: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
a670: 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
a680: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
a690: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4e  ckquote>.**.** N
a6a0: 6f 74 69 63 65 20 74 68 61 74 20 74 68 65 72 65  otice that there
a6b0: 20 69 73 20 61 6e 20 65 78 74 72 61 20 72 6f 77   is an extra row
a6c0: 20 6f 66 20 64 61 74 61 20 63 6f 6e 74 61 69 6e   of data contain
a6d0: 69 6e 67 20 74 68 65 20 63 6f 6c 75 6d 6e 0a 2a  ing the column.*
a6e0: 2a 20 68 65 61 64 65 72 73 2e 20 20 42 75 74 20  * headers.  But 
a6f0: 74 68 65 20 2a 6e 72 6f 77 20 72 65 74 75 72 6e  the *nrow return
a700: 20 76 61 6c 75 65 20 69 73 20 73 74 69 6c 6c 20   value is still 
a710: 33 2e 20 20 2a 6e 63 6f 6c 75 6d 6e 20 69 73 0a  3.  *ncolumn is.
a720: 2a 2a 20 73 65 74 20 74 6f 20 32 2e 20 20 49 6e  ** set to 2.  In
a730: 20 67 65 6e 65 72 61 6c 2c 20 74 68 65 20 6e 75   general, the nu
a740: 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
a750: 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 61 7a 52  nserted into azR
a760: 65 73 75 6c 74 0a 2a 2a 20 77 69 6c 6c 20 62 65  esult.** will be
a770: 20 28 28 2a 6e 72 6f 77 29 20 2b 20 31 29 2a 28   ((*nrow) + 1)*(
a780: 2a 6e 63 6f 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a 2a  *ncolumn)..**.**
a790: 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
a7a0: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
a7b0: 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
a7c0: 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
a7d0: 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74 68  ould .** pass th
a7e0: 65 20 72 65 73 75 6c 74 20 64 61 74 61 20 70 6f  e result data po
a7f0: 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
a800: 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
a810: 20 6f 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72 65   order to .** re
a820: 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
a830: 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
a840: 2d 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  -ed.  Because of
a850: 20 74 68 65 20 77 61 79 20 74 68 65 20 0a 2a 2a   the way the .**
a860: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a870: 28 29 5d 20 68 61 70 70 65 6e 73 2c 20 74 68 65  ()] happens, the
a880: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
a890: 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
a8a0: 6f 20 63 61 6c 6c 20 0a 2a 2a 20 5b 73 71 6c 69  o call .** [sqli
a8b0: 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
a8c0: 63 74 6c 79 2e 20 20 4f 6e 6c 79 20 5b 73 71 6c  ctly.  Only [sql
a8d0: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
a8e0: 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
a8f0: 6c 65 61 73 65 20 0a 2a 2a 20 74 68 65 20 6d 65  lease .** the me
a900: 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
a910: 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
a920: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
a930: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
a940: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
a950: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 65 78  from [sqlite3_ex
a960: 65 63 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ec()]..*/.int sq
a970: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
a980: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
a990: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
a9a0: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
a9b0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
a9c0: 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
a9d0: 20 74 6f 20 62 65 20 65 78 65 63 75 74 65 64 20   to be executed 
a9e0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73  */.  char ***res
a9f0: 75 6c 74 70 2c 20 20 20 20 20 20 20 2f 2a 20 52  ultp,       /* R
aa00: 65 73 75 6c 74 20 77 72 69 74 74 65 6e 20 74 6f  esult written to
aa10: 20 61 20 63 68 61 72 20 2a 5b 5d 20 20 74 68 61   a char *[]  tha
aa20: 74 20 74 68 69 73 20 70 6f 69 6e 74 73 20 74 6f  t this points to
aa30: 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c   */.  int *nrow,
aa40: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
aa50: 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
aa60: 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
aa70: 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f  re */.  int *nco
aa80: 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20 20 2f  lumn,          /
aa90: 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
aaa0: 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
aab0: 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
aac0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
aad0: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
aae0: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
aaf0: 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
ab00: 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
ab10: 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
ab20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
ab30: 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
ab40: 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
ab50: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
ab60: 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c  tines are workal
ab70: 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
ab80: 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
ab90: 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
aba0: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
abb0: 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
abc0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72   The sqlite3_mpr
abd0: 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
abe0: 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
abf0: 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
ac00: 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
ac10: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
ac20: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
ac30: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
ac40: 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
ac50: 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
ac60: 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
ac70: 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
ac80: 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
ac90: 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69  ()].  Both routi
aca0: 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
acb0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
acc0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
acd0: 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
ace0: 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
acf0: 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
ad00: 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
ad10: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e  string..**.** In
ad20: 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
ad30: 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
ad40: 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
ad50: 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
ad60: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
ad70: 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
ad80: 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
ad90: 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
ada0: 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
adb0: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
adc0: 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
add0: 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
ade0: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
adf0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
ae00: 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
ae10: 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
ae20: 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
ae30: 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
ae40: 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  .  This is an.**
ae50: 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
ae60: 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
ae70: 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
ae80: 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
ae90: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
aea0: 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73  ility.  Note als
aeb0: 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
aec0: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
aed0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
aee0: 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
aef0: 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
af00: 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
af10: 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
af20: 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
af30: 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20  ffer.  We admit 
af40: 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
af50: 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
af60: 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
af70: 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
af80: 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
af90: 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
afa0: 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
afb0: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
afc0: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
afd0: 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
afe0: 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
aff0: 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f  ity..**.** As lo
b000: 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
b010: 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
b020: 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
b030: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
b040: 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
b050: 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
b060: 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
b070: 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72  inated.  The fir
b080: 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
b090: 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
b0a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
b0b0: 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
b0c0: 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
b0d0: 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
b0e0: 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
b0f0: 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
b100: 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
b110: 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
b120: 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
b130: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
b140: 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
b150: 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
b160: 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
b170: 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
b180: 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
b190: 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
b1a0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
b1b0: 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
b1c0: 70 72 69 6e 74 66 20 66 6f 72 6d 61 74 74 69 6e  printf formattin
b1d0: 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
b1e0: 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
b1f0: 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
b200: 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
b210: 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
b220: 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e  ** The %q option
b230: 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
b240: 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
b250: 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72  tutes a null-ter
b260: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
b270: 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
b280: 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
b290: 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
b2a0: 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
b2b0: 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
b2c0: 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
b2d0: 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
b2e0: 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62  iteral.  By doub
b2f0: 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
b300: 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
b310: 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
b320: 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
b330: 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
b340: 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
b350: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
b360: 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d   example, so som
b370: 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
b380: 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  e contains text 
b390: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
b3a0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
b3b0: 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
b3c0: 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
b3d0: 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
b3e0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
b3f0: 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
b400: 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
b410: 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
b420: 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
b430: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
b440: 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
b450: 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
b460: 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
b470: 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
b480: 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
b490: 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
b4a0: 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
b4b0: 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
b4c0: 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
b4d0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
b4e0: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
b4f0: 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
b500: 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
b510: 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
b520: 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
b530: 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
b540: 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
b550: 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
b560: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
b570: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
b580: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
b590: 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
b5a0: 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
b5b0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
b5c0: 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
b5d0: 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
b5e0: 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
b5f0: 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
b600: 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
b610: 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
b620: 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
b630: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
b640: 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
b650: 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
b660: 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
b670: 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
b680: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
b690: 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
b6a0: 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
b6b0: 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
b6c0: 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
b6d0: 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64  le you.** should
b6e0: 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
b6f0: 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
b700: 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
b710: 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 0a   into a string .
b720: 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ** literal..**.*
b730: 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  * The %Q option 
b740: 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
b750: 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
b760: 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
b770: 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
b780: 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
b790: 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72 20 69  al string.  Or i
b7a0: 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
b7b0: 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a  in the argument.
b7c0: 2a 2a 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  ** list is a NUL
b7d0: 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
b7e0: 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
b7f0: 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
b800: 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f  ut single.** quo
b810: 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66  tes) in place of
b820: 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20   the %Q option. 
b830: 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
b840: 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
b850: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
b860: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
b870: 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
b880: 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
b890: 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
b8a0: 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
b8b0: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
b8c0: 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
b8d0: 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
b8e0: 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
b8f0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
b900: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
b910: 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
b920: 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
b930: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
b940: 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
b950: 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
b960: 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
b970: 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
b980: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22  ter..**.** The "
b990: 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
b9a0: 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63  ption works exac
b9b0: 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69  tly like "%s" wi
b9c0: 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
b9d0: 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
b9e0: 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
b9f0: 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
ba00: 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
ba10: 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
ba20: 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
ba30: 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
ba40: 72 69 6e 67 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ring..*/.char *s
ba50: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
ba60: 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
ba70: 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
ba80: 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
ba90: 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
baa0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
bab0: 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
bac0: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
bad0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
bae0: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
baf0: 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
bb00: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
bb10: 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
bb20: 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
bb30: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
bb40: 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
bb50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
bb60: 20 6e 65 65 64 73 2e 20 54 68 65 20 64 65 66 61   needs. The defa
bb70: 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ult implementati
bb80: 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65 6d  on.** of the mem
bb90: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
bba0: 75 62 73 79 73 74 65 6d 20 75 73 65 73 20 74 68  ubsystem uses th
bbb0: 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  e malloc(), real
bbc0: 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72 65  loc().** and fre
bbd0: 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20  e() provided by 
bbe0: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
bbf0: 69 62 72 61 72 79 2e 20 20 48 6f 77 65 76 65 72  ibrary.  However
bc00: 2c 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65 20  , if .** SQLite 
bc10: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
bc20: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43   the following C
bc30: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
bc40: 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  cro.**.** <block
bc50: 71 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4f 4d  quote> SQLITE_OM
bc60: 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
bc70: 54 49 4f 4e 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  TION </blockquot
bc80: 65 3e 0a 2a 2a 0a 2a 2a 20 74 68 65 6e 20 6e 6f  e>.**.** then no
bc90: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
bca0: 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  is provided for 
bcb0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 62  these routines b
bcc0: 79 0a 2a 2a 20 53 51 4c 69 74 65 2e 20 20 54 68  y.** SQLite.  Th
bcd0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  e application th
bce0: 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
bcf0: 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 65 78   SQLite is.** ex
bd00: 70 65 63 74 65 64 20 74 6f 20 70 72 6f 76 69 64  pected to provid
bd10: 65 20 69 74 73 20 6f 77 6e 20 69 6d 70 6c 65 6d  e its own implem
bd20: 65 6e 74 61 74 69 6f 6e 2e 20 20 49 66 20 74 68  entation.  If th
bd30: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
bd40: 20 64 6f 65 73 20 70 72 6f 76 69 64 65 20 69 74   does provide it
bd50: 73 20 6f 77 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  s own implementa
bd60: 74 69 6f 6e 20 66 6f 72 20 74 68 65 73 65 20 72  tion for these r
bd70: 6f 75 74 69 6e 65 73 2c 20 74 68 65 6e 0a 2a 2a  outines, then.**
bd80: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 70 72   it must also pr
bd90: 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65  ovide an impleme
bda0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 5b  ntation for.** [
bdb0: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
bdc0: 6c 61 72 6d 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  larm()]..**.** <
bdd0: 62 3e 45 78 63 65 70 74 69 6f 6e 3a 3c 2f 62 3e  b>Exception:</b>
bde0: 20 54 68 65 20 77 69 6e 64 6f 77 73 20 4f 53 20   The windows OS 
bdf0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
be00: 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
be10: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
be20: 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
be30: 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
be40: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
be50: 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
be60: 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
be70: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
be80: 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
be90: 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
bea0: 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
beb0: 6c 61 72 20 77 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar windows.** i
bec0: 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
bed0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bee0: 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
bef0: 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
bf00: 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
bf10: 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
bf20: 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
bf30: 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
bf40: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
bf50: 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 76 6f 69 64  _NOMEM]..*/.void
bf60: 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
bf70: 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
bf80: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
bf90: 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
bfa0: 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
bfb0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
bfc0: 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
bfd0: 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
bfe0: 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64 64 69 74 69  .**.** In additi
bff0: 6f 6e 20 74 6f 20 74 68 65 20 62 61 73 69 63 20  on to the basic 
c000: 74 68 72 65 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  three allocation
c010: 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20 5b 73   routines .** [s
c020: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
c030: 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
c040: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
c050: 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  _realloc()],.** 
c060: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
c070: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
c080: 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68  included with th
c090: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 73 6f 75 72  e SQLite.** sour
c0a0: 63 65 73 20 70 72 6f 76 69 64 65 73 20 74 68 65  ces provides the
c0b0: 20 69 6e 74 65 72 66 61 63 65 73 20 73 68 6f 77   interfaces show
c0c0: 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 0a 2a 2a 20 54  n below..**.** T
c0d0: 68 65 20 66 69 72 73 74 20 6f 66 20 74 68 65 73  he first of thes
c0e0: 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 72  e two routines r
c0f0: 65 74 75 72 6e 73 20 74 68 65 20 61 6d 6f 75 6e  eturns the amoun
c100: 74 20 6f 66 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20  t of memory .** 
c110: 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
c120: 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
c130: 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 20  but not freed). 
c140: 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72   The second.** r
c150: 65 74 75 72 6e 73 20 74 68 65 20 6c 61 72 67 65  eturns the large
c160: 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73  st instantaneous
c170: 20 61 6d 6f 75 6e 74 20 6f 66 20 6f 75 74 73 74   amount of outst
c180: 61 6e 64 69 6e 67 0a 2a 2a 20 6d 65 6d 6f 72 79  anding.** memory
c190: 2e 20 20 54 68 65 20 68 69 67 68 77 61 74 65 72  .  The highwater
c1a0: 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 69   mark is reset i
c1b0: 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
c1c0: 73 0a 2a 2a 20 74 72 75 65 2e 20 20 54 68 65 20  s.** true.  The 
c1d0: 53 51 4c 69 74 65 20 63 6f 72 65 20 64 6f 65 73  SQLite core does
c1e0: 20 6e 6f 74 20 75 73 65 20 65 69 74 68 65 72 20   not use either 
c1f0: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
c200: 73 0a 2a 2a 20 61 6e 64 20 73 6f 20 74 68 65 79  s.** and so they
c210: 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 74 6f 20   do not have to 
c220: 62 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  be implemented b
c230: 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
c240: 6e 0a 2a 2a 20 69 66 20 53 51 4c 49 54 45 5f 4f  n.** if SQLITE_O
c250: 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
c260: 41 54 49 4f 4e 20 69 73 20 64 65 66 69 6e 65 64  ATION is defined
c270: 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
c280: 73 0a 2a 2a 20 61 72 65 20 70 72 6f 76 69 64 65  s.** are provide
c290: 64 20 62 79 20 74 68 65 20 64 65 66 61 75 6c 74  d by the default
c2a0: 20 6d 65 6d 6f 72 79 20 73 75 62 73 79 73 74 65   memory subsyste
c2b0: 6d 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63  m for diagnostic
c2c0: 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2f  .** purposes..*/
c2d0: 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
c2e0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
c2f0: 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
c300: 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
c310: 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
c320: 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
c330: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c340: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
c350: 69 6f 6e 20 41 6c 61 72 6d 73 0a 2a 2a 0a 2a 2a  ion Alarms.**.**
c360: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
c370: 6d 6f 72 79 5f 61 6c 61 72 6d 5d 20 72 6f 75 74  mory_alarm] rout
c380: 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ine is used to r
c390: 65 67 69 73 74 65 72 0a 2a 2a 20 61 20 63 61 6c  egister.** a cal
c3a0: 6c 62 61 63 6b 20 6f 6e 20 6d 65 6d 6f 72 79 20  lback on memory 
c3b0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 76 65 6e 74  allocation event
c3c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  s..**.** This ro
c3d0: 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
c3e0: 6f 72 20 63 6c 65 61 72 73 20 61 20 63 61 6c 6c  or clears a call
c3f0: 62 61 63 6b 73 20 74 68 61 74 20 66 69 72 65 73  backs that fires
c400: 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 61 6d 6f   when.** the amo
c410: 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  unt of memory al
c420: 6c 6f 63 61 74 65 64 20 65 78 63 65 65 64 73 20  located exceeds 
c430: 69 54 68 72 65 73 68 6f 6c 64 2e 20 20 4f 6e 6c  iThreshold.  Onl
c440: 79 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63 61  y.** a single ca
c450: 6c 6c 62 61 63 6b 20 63 61 6e 20 62 65 20 72 65  llback can be re
c460: 67 69 73 74 65 72 65 64 20 61 74 20 61 20 74 69  gistered at a ti
c470: 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 0a 2a  me.  Each call.*
c480: 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * to [sqlite3_me
c490: 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 20 6f 76  mory_alarm()] ov
c4a0: 65 72 77 72 69 74 65 73 20 74 68 65 20 70 72 65  erwrites the pre
c4b0: 76 69 6f 75 73 20 63 61 6c 6c 62 61 63 6b 2e 0a  vious callback..
c4c0: 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
c4d0: 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  is disabled by s
c4e0: 65 74 74 69 6e 67 20 78 43 61 6c 6c 62 61 63 6b  etting xCallback
c4f0: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
c500: 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  inter..** .** Th
c510: 65 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  e parameters to 
c520: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
c530: 20 74 68 65 20 70 41 72 67 20 76 61 6c 75 65 2c   the pArg value,
c540: 20 74 68 65 20 0a 2a 2a 20 61 6d 6f 75 6e 74 20   the .** amount 
c550: 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
c560: 74 6c 79 20 69 6e 20 75 73 65 2c 20 61 6e 64 20  tly in use, and 
c570: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  the size of the.
c580: 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ** allocation th
c590: 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20  at provoked the 
c5a0: 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 20 63  callback.  The c
c5b0: 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 0a 2a 2a 20  allback will.** 
c5c0: 70 72 65 73 75 6d 61 62 6c 79 20 69 6e 76 6f 6b  presumably invok
c5d0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
c5e0: 29 5d 20 74 6f 20 66 72 65 65 20 75 70 20 6d 65  )] to free up me
c5f0: 6d 6f 72 79 20 73 70 61 63 65 2e 0a 2a 2a 20 54  mory space..** T
c600: 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  he callback may 
c610: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
c620: 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
c630: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
c640: 0a 2a 2a 20 62 75 74 20 69 66 20 69 74 20 64 6f  .** but if it do
c650: 65 73 2c 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  es, no additiona
c660: 6c 20 63 61 6c 6c 62 61 63 6b 73 20 77 69 6c 6c  l callbacks will
c670: 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 0a 2a   be invoked by.*
c680: 2a 20 74 68 65 20 72 65 63 75 72 73 69 76 65 20  * the recursive 
c690: 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  calls..**.** The
c6a0: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
c6b0: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  eap_limit()] int
c6c0: 65 72 66 61 63 65 20 77 6f 72 6b 73 20 62 79 20  erface works by 
c6d0: 72 65 67 69 73 74 65 72 69 6e 67 0a 2a 2a 20 61  registering.** a
c6e0: 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20 61 74   memory alarm at
c6f0: 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
c700: 69 6d 69 74 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  imit and invokin
c710: 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
c720: 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
c730: 20 69 6e 20 74 68 65 20 61 6c 61 72 6d 20 63 61   in the alarm ca
c740: 6c 6c 62 61 63 6b 2e 20 20 41 70 70 6c 69 63 61  llback.  Applica
c750: 74 69 6f 6e 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  tion.** programs
c760: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 61 74 74 65   should not atte
c770: 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  mpt to use the [
c780: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
c790: 6c 61 72 6d 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  larm()].** inter
c7a0: 66 61 63 65 20 62 65 63 61 75 73 65 20 64 6f 69  face because doi
c7b0: 6e 67 20 73 6f 20 77 69 6c 6c 20 69 6e 74 65 72  ng so will inter
c7c0: 66 65 72 65 20 77 69 74 68 20 74 68 65 0a 2a 2a  fere with the.**
c7d0: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
c7e0: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 20 6d 6f 64  eap_limit()] mod
c7f0: 75 6c 65 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ule.  This inter
c800: 66 61 63 65 20 69 73 20 65 78 70 6f 73 65 64 0a  face is exposed.
c810: 2a 2a 20 6f 6e 6c 79 20 73 6f 20 74 68 61 74 20  ** only so that 
c820: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 63 61 6e  applications can
c830: 20 70 72 6f 76 69 64 65 20 74 68 65 69 72 20 6f   provide their o
c840: 77 6e 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  wn.** alternativ
c850: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
c860: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65   when the SQLite
c870: 20 63 6f 72 65 20 69 73 0a 2a 2a 20 63 6f 6d 70   core is.** comp
c880: 69 6c 65 64 20 77 69 74 68 20 53 51 4c 49 54 45  iled with SQLITE
c890: 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
c8a0: 4f 43 41 54 49 4f 4e 2e 0a 2a 2f 0a 69 6e 74 20  OCATION..*/.int 
c8b0: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
c8c0: 6c 61 72 6d 28 0a 20 20 76 6f 69 64 28 2a 78 43  larm(.  void(*xC
c8d0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 20 2a 70  allback)(void *p
c8e0: 41 72 67 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Arg, sqlite3_int
c8f0: 36 34 20 75 73 65 64 2c 20 69 6e 74 20 4e 29 2c  64 used, int N),
c900: 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
c910: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
c920: 54 68 72 65 73 68 6f 6c 64 0a 29 3b 0a 0a 0a 2f  Threshold.);.../
c930: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
c940: 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
c950: 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
c960: 63 6b 73 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cks.***.** This 
c970: 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
c980: 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63  s a authorizer c
c990: 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 74 68 65  allback with the
c9a0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
c9b0: 20 20 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72    .** The author
c9c0: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
c9d0: 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
c9e0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
c9f0: 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
ca00: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
ca10: 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
ca20: 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
ca30: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
ca40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
ca50: 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
ca60: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
ca70: 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f  v2()].  At vario
ca80: 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
ca90: 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
caa0: 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
cab0: 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
cac0: 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
cad0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
cae0: 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
caf0: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
cb00: 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
cb10: 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
cb20: 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
cb30: 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72    The authorizer
cb40: 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
cb50: 0a 2a 2a 20 72 65 74 75 72 6e 20 53 51 4c 49 54  .** return SQLIT
cb60: 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f 77 20 74 68  E_OK to allow th
cb70: 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
cb80: 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
cb90: 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
cba0: 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
cbb0: 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
cbc0: 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
cbd0: 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
cbe0: 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
cbf0: 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
cc00: 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
cc10: 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
cc20: 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
cc30: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a  h an error.  .**
cc40: 0a 2a 2a 20 44 65 70 65 6e 64 69 6e 67 20 6f 6e  .** Depending on
cc50: 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 74 68 65   the action, the
cc60: 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
cc70: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45 4e   and [SQLITE_DEN
cc80: 59 5d 20 72 65 74 75 72 6e 0a 2a 2a 20 63 6f 64  Y] return.** cod
cc90: 65 73 20 6d 69 67 68 74 20 6d 65 61 6e 20 73 6f  es might mean so
cca0: 6d 65 74 68 69 6e 67 20 64 69 66 66 65 72 65 6e  mething differen
ccb0: 74 20 6f 72 20 74 68 65 79 20 6d 69 67 68 74 20  t or they might 
ccc0: 6d 65 61 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  mean the same.**
ccd0: 20 74 68 69 6e 67 2e 20 20 49 66 20 74 68 65 20   thing.  If the 
cce0: 61 63 74 69 6f 6e 20 69 73 2c 20 66 6f 72 20 65  action is, for e
ccf0: 78 61 6d 70 6c 65 2c 20 74 6f 20 70 65 72 66 6f  xample, to perfo
cd00: 72 6d 20 61 20 64 65 6c 65 74 65 20 6f 70 65 72  rm a delete oper
cd10: 74 69 6f 6e 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53  tion,.** then [S
cd20: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e  QLITE_IGNORE] an
cd30: 64 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  d [SQLITE_DENY] 
cd40: 62 6f 74 68 20 63 61 75 73 65 20 74 68 65 20 73  both cause the s
cd50: 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 61  tatement compila
cd60: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 61 69 6c 20  tion.** to fail 
cd70: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
cd80: 42 75 74 20 69 66 20 74 68 65 20 61 63 74 69 6f  But if the actio
cd90: 6e 20 69 73 20 74 6f 20 72 65 61 64 20 61 20 73  n is to read a s
cda0: 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 0a 2a  pecific column.*
cdb0: 2a 20 66 72 6f 6d 20 61 20 73 70 65 63 69 66 69  * from a specifi
cdc0: 63 20 74 61 62 6c 65 2c 20 74 68 65 6e 20 5b 53  c table, then [S
cdd0: 51 4c 49 54 45 5f 44 45 4e 59 5d 20 77 69 6c 6c  QLITE_DENY] will
cde0: 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
cdf0: 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  e.** statement t
ce00: 6f 20 66 61 69 6c 20 62 75 74 20 5b 53 51 4c 49  o fail but [SQLI
ce10: 54 45 5f 49 47 4e 4f 52 45 5d 20 77 69 6c 6c 20  TE_IGNORE] will 
ce20: 63 61 75 73 65 20 61 20 4e 55 4c 4c 20 76 61 6c  cause a NULL val
ce30: 75 65 20 74 6f 20 62 65 0a 2a 2a 20 72 65 61 64  ue to be.** read
ce40: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
ce50: 61 63 74 75 61 6c 20 63 6f 6c 75 6d 6e 20 76 61  actual column va
ce60: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  lue..**.** The f
ce70: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
ce80: 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
ce90: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
cea0: 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74 68  opy of.** the th
ceb0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
cec0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
ced0: 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
cee0: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20  terface..** The 
cef0: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
cf00: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
cf10: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a   is an integer .
cf20: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  ** [SQLITE_COPY 
cf30: 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
cf40: 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
cf50: 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
cf60: 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75 74  ion.** to be aut
cf70: 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 61 76  horized.  The av
cf80: 61 69 6c 61 62 6c 65 20 61 63 74 69 6f 6e 20 63  ailable action c
cf90: 6f 64 65 73 20 61 72 65 0a 2a 2a 20 5b 53 51 4c  odes are.** [SQL
cfa0: 49 54 45 5f 43 4f 50 59 20 7c 20 64 6f 63 75 6d  ITE_COPY | docum
cfb0: 65 6e 74 65 64 20 73 65 70 61 72 61 74 65 6c 79  ented separately
cfc0: 5d 2e 20 20 54 68 65 20 74 68 69 72 64 20 74 68  ].  The third th
cfd0: 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a 20 70  rough sixth.** p
cfe0: 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
cff0: 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 73 74   callback are st
d000: 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
d010: 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
d020: 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
d030: 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
d040: 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
d050: 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
d060: 69 73 20 75 73 65 64 20 77 68 65 6e 20 70 72 65  is used when pre
d070: 70 61 72 69 6e 67 20 53 51 4c 20 73 74 61 74 65  paring SQL state
d080: 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
d090: 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63  trusted.** sourc
d0a0: 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
d0b0: 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
d0c0: 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20  ents do not try 
d0d0: 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a  to access data.*
d0e0: 2a 20 74 68 61 74 20 74 68 65 79 20 61 72 65 20  * that they are 
d0f0: 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
d100: 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
d110: 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a   do not try to.*
d120: 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  * execute malici
d130: 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
d140: 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
d150: 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
d160: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
d170: 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
d180: 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
d190: 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
d1a0: 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
d1b0: 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
d1c0: 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
d1d0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
d1e0: 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
d1f0: 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
d200: 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
d210: 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
d220: 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
d230: 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
d240: 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
d250: 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
d260: 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
d270: 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
d280: 6e 67 20 70 72 65 70 61 72 65 64 20 74 68 61 74  ng prepared that
d290: 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
d2a0: 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70 74 20  thing.** except 
d2b0: 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
d2c0: 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20  s.  .**.** Only 
d2d0: 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
d2e0: 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
d2f0: 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
d300: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
d310: 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
d320: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
d330: 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
d340: 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
d350: 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20   previous call. 
d360: 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a   A NULL authoriz
d370: 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f  er means that no
d380: 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
d390: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  * callback is in
d3a0: 76 6f 6b 65 64 2e 20 20 54 68 65 20 64 65 66 61  voked.  The defa
d3b0: 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69  ult authorizer i
d3c0: 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  s NULL..**.** No
d3d0: 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
d3e0: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
d3f0: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
d400: 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69  during .** [sqli
d410: 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
d420: 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
d430: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
d440: 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
d450: 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
d460: 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
d470: 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
d480: 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
d490: 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
d4a0: 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
d4b0: 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
d4c0: 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
d4d0: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
d4e0: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
d4f0: 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
d500: 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
d510: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d520: 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
d530: 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
d540: 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
d550: 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
d560: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
d570: 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
d580: 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
d590: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
d5a0: 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
d5b0: 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
d5c0: 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
d5d0: 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
d5e0: 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
d5f0: 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
d600: 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
d610: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
d620: 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
d630: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
d640: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
d650: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
d660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d670: 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
d680: 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
d690: 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
d6a0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
d6b0: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
d6c0: 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
d6d0: 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
d6e0: 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
d6f0: 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
d700: 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
d710: 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
d720: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
d730: 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
d740: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
d750: 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
d760: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
d770: 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
d780: 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 63 65  to authorizer ce
d790: 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
d7a0: 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
d7b0: 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
d7c0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
d7d0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
d7e0: 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
d7f0: 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
d800: 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
d810: 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
d820: 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
d830: 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
d840: 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
d850: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
d860: 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
d870: 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
d880: 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
d890: 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
d8a0: 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
d8b0: 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72  to be .** author
d8c0: 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
d8d0: 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
d8e0: 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
d8f0: 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 0a  zation callback.
d900: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ** function will
d910: 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
d920: 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
d930: 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
d940: 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
d950: 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
d960: 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
d970: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
d980: 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
d990: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
d9a0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
d9b0: 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
d9c0: 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20 65  ", "temp", .** e
d9d0: 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
d9e0: 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
d9f0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
da00: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
da10: 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
da20: 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
da30: 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
da40: 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
da50: 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
da60: 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
da70: 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
da80: 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
da90: 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
daa0: 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53   .** top-level S
dab0: 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
dac0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
dad0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
dae0: 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
daf0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
db00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
db10: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
db20: 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
db30: 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
db40: 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
db50: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
db60: 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
db70: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
db80: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
db90: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
dba0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
dbb0: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
dbc0: 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
dbd0: 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
dbe0: 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
dbf0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
dc00: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
dc10: 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
dc20: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
dc30: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
dc40: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
dc50: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
dc60: 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
dc70: 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
dc80: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
dc90: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
dca0: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
dcb0: 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
dcc0: 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
dcd0: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
dce0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
dcf0: 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
dd00: 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
dd10: 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
dd20: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
dd30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dd40: 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
dd50: 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
dd60: 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
dd70: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
dd80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dd90: 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
dda0: 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
ddb0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
ddc0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
ddd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dde0: 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
ddf0: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
de00: 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
de10: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
de20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
de30: 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
de40: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
de50: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
de60: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
de70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
de80: 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
de90: 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
dea0: 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
deb0: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
dec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
ded0: 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
dee0: 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
def0: 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
df00: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
df10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
df20: 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
df30: 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
df40: 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
df50: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
df60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
df70: 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
df80: 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
df90: 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
dfa0: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
dfb0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
dfc0: 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
dfd0: 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
dfe0: 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
dff0: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
e000: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
e010: 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
e020: 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
e030: 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
e040: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
e050: 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
e060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
e070: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
e080: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
e090: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
e0a0: 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
e0b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
e0c0: 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
e0d0: 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
e0e0: 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
e0f0: 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
e100: 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
e110: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
e120: 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
e130: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
e140: 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
e150: 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
e160: 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
e170: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
e180: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
e190: 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
e1a0: 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
e1b0: 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
e1c0: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
e1d0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e1e0: 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
e1f0: 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
e200: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
e210: 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
e220: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e230: 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
e240: 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
e250: 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
e260: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
e270: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e280: 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
e290: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
e2a0: 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
e2b0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
e2c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e2d0: 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
e2e0: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
e2f0: 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
e300: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
e310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e320: 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
e330: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
e340: 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
e350: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
e360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e370: 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
e380: 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
e390: 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
e3a0: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
e3b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
e3c0: 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
e3d0: 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
e3e0: 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
e3f0: 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
e400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
e410: 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
e420: 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
e430: 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
e440: 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
e450: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
e460: 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
e470: 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f   31   /* Functio
e480: 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  n Name   NULL   
e490: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
e4a0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
e4b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
e4c0: 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
e4d0: 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
e4e0: 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
e4f0: 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
e500: 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
e510: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
e520: 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
e530: 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
e540: 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
e550: 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
e560: 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
e570: 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
e580: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  tatements..** Th
e590: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
e5a0: 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
e5b0: 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
e5c0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
e5d0: 61 74 20 74 68 65 20 66 69 72 73 74 20 5b 73 71  at the first [sq
e5e0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
e5f0: 72 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  r the evaluation
e600: 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
e610: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  ment..** The cal
e620: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
e630: 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
e640: 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
e650: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
e660: 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
e670: 6e 74 20 66 69 6e 69 73 68 65 73 20 61 6e 64 20  nt finishes and 
e680: 69 6e 63 6c 75 64 65 73 0a 2a 2a 20 69 6e 66 6f  includes.** info
e690: 72 6d 61 74 69 6f 6e 20 6f 6e 20 68 6f 77 20 6c  rmation on how l
e6a0: 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
e6b0: 6e 74 20 72 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nt ran..**.** Th
e6c0: 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  e sqlite3_profil
e6d0: 65 28 29 20 41 50 49 20 69 73 20 63 75 72 72 65  e() API is curre
e6e0: 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20  ntly considered 
e6f0: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
e700: 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20 74  .** is subject t
e710: 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69  o change..*/.voi
e720: 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
e730: 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
e740: 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
e750: 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
e760: 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
e770: 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
e780: 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
e790: 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
e7a0: 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
e7b0: 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
e7c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
e7d0: 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
e7e0: 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
e7f0: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
e800: 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c  configures a cal
e810: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d  lback function -
e820: 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
e830: 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 0a 2a 2a  llback - that.**
e840: 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   is invoked peri
e850: 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
e860: 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
e870: 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
e880: 78 65 63 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  xec()],.** [sqli
e890: 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
e8a0: 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
e8b0: 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70  le()].  An examp
e8c0: 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 20  le use for this 
e8d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
e8e0: 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
e8f0: 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
e900: 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
e910: 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
e920: 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
e930: 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65  ked once for eve
e940: 72 79 20 4e 20 76 69 72 74 75 61 6c 20 6d 61 63  ry N virtual mac
e950: 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 0a 2a 2a  hine opcodes,.**
e960: 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
e970: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
e980: 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
e990: 2e 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63  . The progress c
e9a0: 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 74 73 65 6c  allback.** itsel
e9b0: 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20  f is identified 
e9c0: 62 79 20 74 68 65 20 74 68 69 72 64 20 61 72 67  by the third arg
e9d0: 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75  ument to this fu
e9e0: 6e 63 74 69 6f 6e 2e 20 54 68 65 20 66 6f 75 72  nction. The four
e9f0: 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  th.** argument t
ea00: 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
ea10: 69 73 20 61 20 76 6f 69 64 20 70 6f 69 6e 74 65  is a void pointe
ea20: 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
ea30: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
ea40: 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 65 61  k.** function ea
ea50: 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e  ch time it is in
ea60: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  voked..**.** If 
ea70: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
ea80: 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
ea90: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72  ite3_step()], or
eaa0: 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
eab0: 62 6c 65 28 29 5d 0a 2a 2a 20 72 65 73 75 6c 74  ble()].** result
eac0: 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 20  s in fewer than 
ead0: 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67 20  N opcodes being 
eae0: 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74  executed, then t
eaf0: 68 65 20 70 72 6f 67 72 65 73 73 20 0a 2a 2a 20  he progress .** 
eb00: 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65  callback is neve
eb10: 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 0a 2a  r invoked..** .*
eb20: 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  * Only a single 
eb30: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
eb40: 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
eb50: 65 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72  e registered for
eb60: 20 65 61 63 68 0a 2a 2a 20 6f 70 65 6e 20 64 61   each.** open da
eb70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
eb80: 6e 2e 20 20 45 76 65 72 79 20 63 61 6c 6c 20 74  n.  Every call t
eb90: 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  o sqlite3_progre
eba0: 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20  ss_handler().** 
ebb0: 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20 72  overwrites the r
ebc0: 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 70 72  esults of the pr
ebd0: 65 76 69 6f 75 73 20 63 61 6c 6c 2e 0a 2a 2a 20  evious call..** 
ebe0: 54 6f 20 72 65 6d 6f 76 65 20 74 68 65 20 70 72  To remove the pr
ebf0: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
ec00: 61 6c 74 6f 67 65 74 68 65 72 2c 20 70 61 73 73  altogether, pass
ec10: 20 4e 55 4c 4c 20 61 73 20 74 68 65 20 74 68 69   NULL as the thi
ec20: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
ec30: 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
ec40: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72  .**.** If the pr
ec50: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
ec60: 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
ec70: 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74   other than 0, t
ec80: 68 65 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  hen the current 
ec90: 0a 2a 2a 20 71 75 65 72 79 20 69 73 20 69 6d 6d  .** query is imm
eca0: 65 64 69 61 74 65 6c 79 20 74 65 72 6d 69 6e 61  ediately termina
ecb0: 74 65 64 20 61 6e 64 20 61 6e 79 20 64 61 74 61  ted and any data
ecc0: 62 61 73 65 20 63 68 61 6e 67 65 73 20 72 6f 6c  base changes rol
ecd0: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  led back..** The
ece0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 5b 73 71 6c   containing [sql
ecf0: 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
ed00: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
ed10: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  or.** [sqlite3_g
ed20: 65 74 5f 74 61 62 6c 65 28 29 5d 20 63 61 6c 6c  et_table()] call
ed30: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
ed40: 49 4e 54 45 52 52 55 50 54 2e 20 20 20 54 68 69  INTERRUPT.   Thi
ed50: 73 20 66 65 61 74 75 72 65 0a 2a 2a 20 63 61 6e  s feature.** can
ed60: 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
ed70: 61 6d 70 6c 65 2c 20 74 6f 20 69 6d 70 6c 65 6d  ample, to implem
ed80: 65 6e 74 20 74 68 65 20 22 43 61 6e 63 65 6c 22  ent the "Cancel"
ed90: 20 62 75 74 74 6f 6e 20 6f 6e 20 61 0a 2a 2a 20   button on a.** 
eda0: 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
edb0: 62 6f 78 20 69 6e 20 61 20 47 55 49 2e 0a 2a 2f  box in a GUI..*/
edc0: 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
edd0: 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
ede0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
edf0: 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
ee00: 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
ee10: 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
ee20: 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
ee30: 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f 70  nection.**.** Op
ee40: 65 6e 20 74 68 65 20 73 71 6c 69 74 65 20 64 61  en the sqlite da
ee50: 74 61 62 61 73 65 20 66 69 6c 65 20 22 66 69 6c  tabase file "fil
ee60: 65 6e 61 6d 65 22 2e 20 20 54 68 65 20 22 66 69  ename".  The "fi
ee70: 6c 65 6e 61 6d 65 22 20 69 73 20 55 54 46 2d 38  lename" is UTF-8
ee80: 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 66 6f 72 20  .** encoded for 
ee90: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
eea0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
eeb0: 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 55 54 46  en_v2()] and UTF
eec0: 2d 31 36 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 69  -16 encoded.** i
eed0: 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
eee0: 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c  e order for [sql
eef0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
ef00: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d  ** An [sqlite3*]
ef10: 20 68 61 6e 64 6c 65 20 69 73 20 72 65 74 75 72   handle is retur
ef20: 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
ef30: 65 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72 6f  en.** if an erro
ef40: 72 20 6f 63 63 75 72 73 2e 20 49 66 20 74 68 65  r occurs. If the
ef50: 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
ef60: 6e 65 64 20 28 6f 72 20 63 72 65 61 74 65 64 29  ned (or created)
ef70: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 0a 2a   successfully,.*
ef80: 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4f  * then [SQLITE_O
ef90: 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
efa0: 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  Otherwise an err
efb0: 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
efc0: 6e 65 64 2e 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ned. The.** [sql
efd0: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
efe0: 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
eff0: 67 31 36 28 29 5d 20 20 72 6f 75 74 69 6e 65 73  g16()]  routines
f000: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
f010: 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
f020: 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
f030: 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
f040: 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
f050: 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
f060: 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
f070: 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
f080: 38 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  8 if.** [sqlite3
f090: 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c  _open()] or [sql
f0a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
f0b0: 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
f0c0: 20 55 54 46 2d 31 36 20 69 66 20 5b 73 71 6c 69   UTF-16 if [sqli
f0d0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
f0e0: 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
f0f0: 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
f100: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
f110: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
f120: 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61  esources associa
f130: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
f140: 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c  [sqlite3*] handl
f150: 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
f160: 61 73 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ased by passing 
f170: 69 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  it to.** [sqlite
f180: 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
f190: 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
f1a0: 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
f1b0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
f1c0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
f1d0: 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 5b 73 71  e works like [sq
f1e0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 65 78  lite3_open()] ex
f1f0: 63 65 70 74 20 74 68 61 74 0a 2a 2a 20 70 72 6f  cept that.** pro
f200: 76 69 64 65 73 20 74 77 6f 20 61 64 64 69 74 69  vides two additi
f210: 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
f220: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
f230: 6f 6e 74 72 6f 6c 20 6f 76 65 72 20 74 68 65 0a  ontrol over the.
f240: 2a 2a 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  ** new database 
f250: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
f260: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
f270: 20 63 61 6e 20 62 65 20 6f 6e 65 20 6f 66 3a 0a   can be one of:.
f280: 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
f290: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
f2a0: 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c  _READONLY].** <l
f2b0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
f2c0: 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a 2a 20 3c  _READWRITE].** <
f2d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
f2e0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
f2f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
f300: 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  TE].** </ol>.**.
f310: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 76 61 6c  ** The first val
f320: 75 65 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74  ue opens the dat
f330: 61 62 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  abase read-only.
f340: 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
f350: 65 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 70 72  e does.** not pr
f360: 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20  eviously exist, 
f370: 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
f380: 72 6e 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  rned.  The secon
f390: 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  d option opens.*
f3a0: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  * the database f
f3b0: 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
f3c0: 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
f3d0: 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 20 6f  le, or reading o
f3e0: 6e 6c 79 20 69 66 0a 2a 2a 20 69 66 20 74 68 65  nly if.** if the
f3f0: 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
f400: 72 6f 74 65 63 74 65 64 2e 20 20 49 6e 20 65 69  rotected.  In ei
f410: 74 68 65 72 20 63 61 73 65 20 74 68 65 20 64 61  ther case the da
f420: 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
f430: 61 64 79 0a 2a 2a 20 65 78 69 73 74 20 6f 72 20  ady.** exist or 
f440: 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
f450: 72 6e 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  rned.  The third
f460: 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 20 74 68   option opens th
f470: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 6f  e database.** fo
f480: 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
f490: 69 74 69 6e 67 20 61 6e 64 20 63 72 65 61 74 65  iting and create
f4a0: 73 20 69 74 20 69 66 20 69 74 20 64 6f 65 73 20  s it if it does 
f4b0: 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
f4c0: 74 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  t..** The third 
f4d0: 6f 70 74 69 6f 6e 73 20 69 73 20 62 65 68 61 76  options is behav
f4e0: 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
f4f0: 79 73 20 75 73 65 64 20 66 6f 72 20 5b 73 71 6c  ys used for [sql
f500: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
f510: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
f520: 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  n16()]..**.** If
f530: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
f540: 20 22 3a 6d 65 6d 6f 72 79 3a 22 20 6f 72 20 61   ":memory:" or a
f550: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
f560: 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 0a  then an private.
f570: 2a 2a 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ** in-memory dat
f580: 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64  abase is created
f590: 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
f5a0: 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65  ion.  This in-me
f5b0: 6d 6f 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65  mory.** database
f5c0: 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
f5d0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
f5e0: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
f5f0: 73 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  sed.  Future.** 
f600: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
f610: 65 20 6d 69 67 68 74 20 6d 61 6b 65 20 75 73 65  e might make use
f620: 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
f630: 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
f640: 0a 2a 2a 20 74 68 61 74 20 62 65 67 69 6e 20 77  .** that begin w
f650: 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
f660: 61 63 74 65 72 2e 20 20 49 74 20 69 73 20 72 65  acter.  It is re
f670: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 0a  commended that .
f680: 2a 2a 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  ** when a databa
f690: 73 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 61 6c  se filename real
f6a0: 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
f6b0: 74 68 0a 2a 2a 20 22 3a 22 20 74 68 61 74 20 79  th.** ":" that y
f6c0: 6f 75 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ou prefix the fi
f6d0: 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
f6e0: 74 68 6e 61 6d 65 20 6c 69 6b 65 20 22 2e 2f 22  thname like "./"
f6f0: 20 74 6f 0a 2a 2a 20 61 76 6f 69 64 20 61 6d 62   to.** avoid amb
f700: 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  iguity..**.** Th
f710: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
f720: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
f730: 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
f740: 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
f750: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
f760: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
f770: 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
f780: 73 74 65 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61  stem .** interfa
f790: 63 65 20 74 68 61 74 20 74 68 65 20 6e 65 77 20  ce that the new 
f7a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f7b0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
f7c0: 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
f7d0: 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
f7e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
f7f0: 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
f800: 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20  sqlite3_vfs].** 
f810: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
f820: 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
f830: 20 77 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   windows users:<
f840: 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
f850: 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
f860: 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
f870: 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  .** of [sqlite3_
f880: 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  open()] and [sql
f890: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
f8a0: 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
f8b0: 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
f8c0: 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
f8d0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
f8e0: 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
f8f0: 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
f900: 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
f910: 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
f920: 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
f930: 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
f940: 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
f950: 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71  3_open()] or [sq
f960: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
f970: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
f980: 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
f990: 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
f9a0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
f9b0: 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
f9c0: 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
f9d0: 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
f9e0: 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
f9f0: 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
fa00: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
fa10: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
fa20: 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
fa30: 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
fa40: 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
fa50: 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
fa60: 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
fa70: 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
fa80: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
fa90: 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
faa0: 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
fab0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
fac0: 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
fad0: 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
fae0: 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
faf0: 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
fb00: 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
fb10: 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
fb20: 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
fb30: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
fb40: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
fb50: 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
fb60: 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
fb70: 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
fb80: 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
fb90: 67 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ges.**.** The sq
fba0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
fbb0: 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
fbc0: 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a  s the numeric.**
fbd0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
fbe0: 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53  sult code] or [S
fbf0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
fc00: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
fc10: 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20  lt code].** for 
fc20: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
fc30: 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
fc40: 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
fc50: 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71  ated.** with [sq
fc60: 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20 27 64  lite3] handle 'd
fc70: 62 27 2e 20 20 49 66 20 61 20 70 72 69 6f 72 20  b'.  If a prior 
fc80: 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 20  API call failed 
fc90: 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20  but the.** most 
fca0: 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
fcb0: 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
fcc0: 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
fcd0: 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
fce0: 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ().** is undefin
fcf0: 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ed. .**.** The s
fd00: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
fd10: 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
fd20: 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
fd30: 67 6c 69 73 68 2d 6c 61 6e 67 61 75 67 65 0a 2a  glish-langauge.*
fd40: 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
fd50: 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
fd60: 20 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20   as either UTF8 
fd70: 6f 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74  or UTF16 respect
fd80: 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  ively..** Memory
fd90: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
fda0: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
fdb0: 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
fdc0: 65 72 6e 61 6c 6c 79 2e 20 20 54 68 65 20 0a 2a  ernally.  The .*
fdd0: 2a 20 73 74 72 69 6e 67 20 6d 61 79 20 62 65 20  * string may be 
fde0: 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
fdf0: 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 75  eallocated by su
fe00: 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
fe10: 6f 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65  o SQLite.** inte
fe20: 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
fe30: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20  .**.** Calls to 
fe40: 6d 61 6e 79 20 73 71 6c 69 74 65 33 5f 2a 20 66  many sqlite3_* f
fe50: 75 6e 63 74 69 6f 6e 73 20 73 65 74 20 74 68 65  unctions set the
fe60: 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
fe70: 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 0a  string returned.
fe80: 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65  ** by [sqlite3_e
fe90: 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69  rrcode()], [sqli
fea0: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61  te3_errmsg()], a
feb0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
fec0: 73 67 31 36 28 29 5d 0a 2a 2a 20 28 6f 76 65 72  sg16()].** (over
fed0: 77 72 69 74 69 6e 67 20 74 68 65 20 70 72 65 76  writing the prev
fee0: 69 6f 75 73 20 76 61 6c 75 65 73 29 2e 20 4e 6f  ious values). No
fef0: 74 65 20 74 68 61 74 20 63 61 6c 6c 73 20 74 6f  te that calls to
ff00: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
ff10: 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  e()],.** [sqlite
ff20: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
ff30: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
ff40: 31 36 28 29 5d 20 74 68 65 6d 73 65 6c 76 65 73  16()] themselves
ff50: 20 64 6f 20 6e 6f 74 20 61 66 66 65 63 74 20 74   do not affect t
ff60: 68 65 0a 2a 2a 20 72 65 73 75 6c 74 73 20 6f 66  he.** results of
ff70: 20 66 75 74 75 72 65 20 69 6e 76 6f 63 61 74 69   future invocati
ff80: 6f 6e 73 2e 20 20 43 61 6c 6c 73 20 74 6f 20 41  ons.  Calls to A
ff90: 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  PI routines that
ffa0: 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e 0a 2a   do not return.*
ffb0: 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  * an error code 
ffc0: 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74  (example: [sqlit
ffd0: 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
ffe0: 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 63 68 61 6e  ) do not.** chan
fff0: 67 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ge the error cod
10000 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
10010 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 49 6e 74  is routine.  Int
10020 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65  erfaces that are
10030 0a 2a 2a 20 6e 6f 74 20 61 73 73 6f 63 69 61 74  .** not associat
10040 65 64 20 77 69 74 68 20 61 20 73 70 65 63 69 66  ed with a specif
10050 69 63 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ic database conn
10060 65 63 74 69 6f 6e 20 28 65 78 61 6d 70 6c 65 73  ection (examples
10070 3a 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 70  :.** [sqlite3_mp
10080 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c  rintf()] or [sql
10090 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
100a0 65 64 5f 63 61 63 68 65 28 29 5d 20 64 6f 20 6e  ed_cache()] do n
100b0 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ot change.** the
100c0 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 20 20 0a   return code.  .
100d0 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e 67 20 6e  **.** Assuming n
100e0 6f 20 6f 74 68 65 72 20 69 6e 74 65 72 76 65 6e  o other interven
100f0 69 6e 67 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ing sqlite3_* AP
10100 49 20 63 61 6c 6c 73 20 61 72 65 20 6d 61 64 65  I calls are made
10110 2c 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  , the error.** c
10120 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  ode returned by 
10130 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
10140 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
10150 20 74 68 65 20 73 61 6d 65 20 65 72 72 6f 72 20   the same error 
10160 61 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  as.** the string
10170 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
10180 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
10190 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
101a0 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  rmsg16()]..*/.in
101b0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
101c0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
101d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
101e0 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
101f0 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
10200 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
10210 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
10220 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
10230 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
10240 65 63 74 0a 2a 2a 0a 2a 2a 20 49 6e 73 74 61 6e  ect.**.** Instan
10250 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
10260 74 20 72 65 70 72 65 73 65 6e 74 20 73 69 6e 67  t represent sing
10270 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
10280 73 2e 20 20 54 68 69 73 0a 2a 2a 20 69 73 20 76  s.  This.** is v
10290 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
102a0 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
102b0 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a  atement" or a .*
102c0 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
102d0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
102e0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
102f0 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  ment"..** .** Th
10300 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
10310 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
10320 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
10330 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
10340 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
10350 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
10360 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
10370 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
10380 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
10390 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
103a0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  Bind values to h
103b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 75  ost parameters u
103c0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71  sing.**      [sq
103d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
103e0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
103f0 20 69 6e 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a   interfaces]..**
10400 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
10410 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
10420 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
10430 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
10440 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
10450 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
10460 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
10470 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
10480 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
10490 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
104a0 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
104b0 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
104c0 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
104d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
104e0 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
104f0 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
10500 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
10510 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
10520 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
10530 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
10540 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
10550 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
10560 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
10570 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
10580 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
10590 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
105a0 6e 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  nt.**.** To exec
105b0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
105c0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
105d0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
105e0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
105f0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
10600 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
10610 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nes. .**.** The 
10620 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 22  first argument "
10630 64 62 22 20 69 73 20 61 6e 20 5b 73 71 6c 69 74  db" is an [sqlit
10640 65 33 20 7c 20 53 51 4c 69 74 65 20 64 61 74 61  e3 | SQLite data
10650 62 61 73 65 20 68 61 6e 64 6c 65 5d 20 0a 2a 2a  base handle] .**
10660 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
10670 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b   prior call to [
10680 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
10690 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
106a0 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  2()].** or [sqli
106b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
106c0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
106d0 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73 20  ument "zSql" is 
106e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
106f0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
10700 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
10710 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
10720 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
10730 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
10740 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
10750 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
10760 73 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e 64  s uses UTF-8 and
10770 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
10780 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
10790 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
107a0 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
107b0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74  *.** If the nByt
107c0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
107d0 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c  ss.** than zero,
107e0 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
107f0 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  ad up to the fir
10800 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
10810 6f 72 2e 20 20 49 66 0a 2a 2a 20 6e 42 79 74 65  or.  If.** nByte
10820 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
10830 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
10840 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
10850 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 65 61  of .** bytes rea
10860 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68  d from zSql.  Wh
10870 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
10880 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
10890 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
108a0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
108b0 66 69 72 73 74 20 27 5c 30 30 30 27 20 63 68 61  first '\000' cha
108c0 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20 75 6e  racter or .** un
108d0 74 69 6c 20 74 68 65 20 6e 42 79 74 65 2d 74 68  til the nByte-th
108e0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
108f0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
10900 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  .** *pzTail is m
10910 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
10920 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20 70  the first byte p
10930 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
10940 68 65 20 66 69 72 73 74 0a 2a 2a 20 53 51 4c 20  he first.** SQL 
10950 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
10960 6c 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  l.  This routine
10970 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73 20 74   only compiles t
10980 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
10990 6e 74 0a 2a 2a 20 69 6e 20 7a 53 71 6c 2c 20 73  nt.** in zSql, s
109a0 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
109b0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68  t pointing to wh
109c0 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
109d0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70  piled..**.** *pp
109e0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
109f0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
10a00 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  led .** [sqlite3
10a10 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61 74  _stmt | SQL stat
10a20 65 6d 65 6e 74 20 73 74 72 75 63 74 75 72 65 5d  ement structure]
10a30 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
10a40 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
10a50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
10a60 20 20 4f 72 20 69 66 20 74 68 65 72 65 20 69 73    Or if there is
10a70 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
10a80 6d 74 20 6d 61 79 20 62 65 0a 2a 2a 20 73 65 74  mt may be.** set
10a90 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68   to NULL.  If th
10aa0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
10ab0 74 61 69 6e 65 64 20 6e 6f 20 53 51 4c 20 28 69  tained no SQL (i
10ac0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
10ad0 6e 64 0a 2a 2a 20 65 6d 70 74 79 20 73 74 72 69  nd.** empty stri
10ae0 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
10af0 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
10b00 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 54   set to NULL.  T
10b10 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 70 72  he calling.** pr
10b20 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
10b30 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
10b40 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
10b50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
10b60 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
10b70 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
10b80 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
10b90 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a  ed with it..**.*
10ba0 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  * On success, [S
10bb0 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
10bc0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
10bd0 65 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  e an .** [SQLITE
10be0 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63  _ERROR | error c
10bf0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
10c00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10c10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
10c20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
10c30 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
10c40 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
10c50 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
10c60 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
10c70 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
10c80 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
10c90 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
10ca0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
10cb0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
10cc0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
10cd0 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76  ed..** In the "v
10ce0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
10cf0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
10d00 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
10d10 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
10d20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
10d30 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
10d40 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a   copy of the .**
10d50 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
10d60 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
10d70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
10d80 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
10d90 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69  o.** behave a di
10da0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f  fferently in two
10db0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
10dc0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20  >.** <li>.** If 
10dd0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
10de0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
10df0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
10e00 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
10e10 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
10e20 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
10e30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
10e40 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
10e50 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
10e60 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
10e70 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
10e80 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68  it again.  If th
10e90 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
10ea0 6e 67 65 64 20 69 6e 20 61 20 77 61 79 0a 2a 2a  nged in a way.**
10eb0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
10ec0 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
10ed0 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
10ee0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
10ef0 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
10f00 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
10f10 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
10f20 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
10f30 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  r, [SQLITE_SCHEM
10f40 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66  A] is.** now a f
10f50 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c  atal error.  Cal
10f60 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
10f70 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69  epare_v2()] agai
10f80 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20  n will not make 
10f90 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20  the.** error go 
10fa0 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65  away.  Note: use
10fb0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
10fc0 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ()] to find the 
10fd0 74 65 78 74 20 6f 66 20 74 68 65 20 70 61 72 73  text of the pars
10fe0 69 6e 67 0a 2a 2a 20 65 72 72 6f 72 20 74 68 61  ing.** error tha
10ff0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20  t results in an 
11000 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
11010 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e  return..** </li>
11020 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57  .**.** <li>.** W
11030 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
11040 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  urs, .** [sqlite
11050 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
11060 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
11070 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20 5b 53   detailed .** [S
11080 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65  QLITE_ERROR | re
11090 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
110a0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  * [SQLITE_IOERR_
110b0 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
110c0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 73 75  result codes] su
110d0 63 68 20 61 73 20 64 69 72 65 63 74 6c 79 2e 0a  ch as directly..
110e0 2a 2a 20 54 68 65 20 6c 65 67 61 63 79 20 62 65  ** The legacy be
110f0 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 20  havior was that 
11100 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
11110 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
11120 72 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a 2a 20  rn a generic.** 
11130 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
11140 65 73 75 6c 74 20 63 6f 64 65 20 61 6e 64 20 79  esult code and y
11150 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  ou would have to
11160 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
11170 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
11180 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f  e3_reset()] in o
11190 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
111a0 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
111b0 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
111c0 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76  ..** With the "v
111d0 32 22 20 70 72 65 70 61 72 65 20 69 6e 74 65 72  2" prepare inter
111e0 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
111f0 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
11200 20 74 68 65 20 65 72 72 6f 72 20 69 73 0a 2a 2a   the error is.**
11210 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
11220 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
11230 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
11240 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
11250 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
11260 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
11270 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
11280 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
11290 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
112a0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
112b0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
112c0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
112d0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
112e0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
112f0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
11300 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
11310 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
11320 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
11330 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
11340 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
11350 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
11360 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
11370 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
11380 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
11390 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
113a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
113b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
113c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
113d0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
113e0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
113f0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
11400 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
11410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
11420 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
11430 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
11440 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
11450 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
11460 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
11470 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
11480 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
11490 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
114a0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
114b0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
114c0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
114d0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
114e0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
114f0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
11500 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
11510 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
11520 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
11530 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
11540 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
11550 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
11560 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
11570 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
11580 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
11590 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
115a0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
115b0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
115c0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
115d0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
115e0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
115f0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
11600 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
11610 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
11620 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
11630 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
11640 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
11650 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
11660 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
11670 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
11680 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
11690 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
116a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
116b0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
116c0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
116d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
116e0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
116f0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
11700 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
11710 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
11720 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
11730 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
11740 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
11750 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
11760 52 45 46 3a 20 20 44 79 6e 61 6d 69 63 61 6c 6c  REF:  Dynamicall
11770 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
11780 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ject.**.** SQLit
11790 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
117a0 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20 76 61  yping for the va
117b0 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
117c0 20 56 61 6c 75 65 73 20 63 61 6e 20 0a 2a 2a 20   Values can .** 
117d0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
117e0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
117f0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
11800 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 20 20 57 68  Bs, or NULL.  Wh
11810 65 6e 0a 2a 2a 20 70 61 73 73 69 6e 67 20 61 72  en.** passing ar
11820 6f 75 6e 64 20 76 61 6c 75 65 73 20 69 6e 74 65  ound values inte
11830 72 6e 61 6c 6c 79 2c 20 65 61 63 68 20 76 61 6c  rnally, each val
11840 75 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ue is represente
11850 64 20 61 73 0a 2a 2a 20 61 6e 20 69 6e 73 74 61  d as.** an insta
11860 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
11870 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
11880 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
11890 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
118a0 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
118b0 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75 6e 63  I3REF:  SQL Func
118c0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
118d0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
118e0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
118f0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
11900 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
11910 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
11920 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
11930 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  t.  A pointer to
11940 20 73 75 63 68 20 61 6e 20 6f 62 6a 65 63 74 20   such an object 
11950 69 73 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  is the.** first 
11960 70 61 72 61 6d 65 74 65 72 20 74 6f 20 75 73 65  parameter to use
11970 72 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  r-defined SQL fu
11980 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65  nctions..*/.type
11990 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
119a0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
119b0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
119c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 42 69  ** CAPI3REF:  Bi
119d0 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
119e0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
119f0 6e 74 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  nts.**.** In the
11a00 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70   SQL strings inp
11a10 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
11a20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
11a30 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
11a40 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6c 69  * one or more li
11a50 74 65 72 61 6c 73 20 63 61 6e 20 62 65 20 72 65  terals can be re
11a60 70 6c 61 63 65 20 62 79 20 61 20 70 61 72 61 6d  place by a param
11a70 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20 74  eter in one of t
11a80 68 65 73 65 0a 2a 2a 20 66 6f 72 6d 73 3a 0a 2a  hese.** forms:.*
11a90 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
11aa0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
11ab0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 41 41 41  NN.** <li>  :AAA
11ac0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41 41 41 0a 2a  .** <li>  @AAA.*
11ad0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
11ae0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
11af0 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72  he parameter for
11b00 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e  ms shown above N
11b10 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  NN is an integer
11b20 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 41 41 41   literal,.** AAA
11b30 20 69 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65   is an alphanume
11b40 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 20 61  ric identifier a
11b50 6e 64 20 56 56 56 20 69 73 20 61 20 76 61 72 69  nd VVV is a vari
11b60 61 62 6c 65 20 6e 61 6d 65 20 61 63 63 6f 72 64  able name accord
11b70 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 73 79  ing.** to the sy
11b80 6e 74 61 78 20 72 75 6c 65 73 20 6f 66 20 74 68  ntax rules of th
11b90 65 20 54 43 4c 20 70 72 6f 67 72 61 6d 6d 69 6e  e TCL programmin
11ba0 67 20 6c 61 6e 67 75 61 67 65 2e 0a 2a 2a 20 54  g language..** T
11bb0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
11bc0 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  se parameters (a
11bd0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
11be0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
11bf0 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
11c00 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
11c10 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
11c20 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
11c30 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
11c40 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
11c50 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
11c60 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 6c 77  *() routines alw
11c70 61 79 73 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ays is a pointer
11c80 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
11c90 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
11ca0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
11cb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
11cc0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 69 74 73 20  v2()] or.** its 
11cd0 76 61 72 69 61 6e 74 73 2e 20 20 54 68 65 20 73  variants.  The s
11ce0 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
11cf0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
11d00 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
11d10 74 6f 20 62 65 20 73 65 74 2e 20 20 54 68 65 20  to be set.  The 
11d20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
11d30 68 61 73 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 20  has.** an index 
11d40 6f 66 20 31 2e 20 57 68 65 6e 20 74 68 65 20 73  of 1. When the s
11d50 61 6d 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  ame named parame
11d60 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
11d70 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
11d80 6e 64 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71  nd.** and subseq
11d90 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
11da0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
11db0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
11dc0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
11dd0 20 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 0a    The index for.
11de0 2a 2a 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  ** named paramet
11df0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
11e00 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
11e10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
11e20 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
11e30 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
11e40 2e 20 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72  .  The index for
11e50 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 70 61 72 61 6d   "?NNN".** param
11e60 65 74 65 73 20 69 73 20 74 68 65 20 76 61 6c 75  etes is the valu
11e70 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65  e of NNN..** The
11e80 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
11e90 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
11ea0 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
11eb0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 53  e.** parameter S
11ec0 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42  QLITE_MAX_VARIAB
11ed0 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66 61 75  LE_NUMBER (defau
11ee0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
11ef0 2a 2a 20 53 65 65 20 3c 61 20 68 72 65 66 3d 22  ** See <a href="
11f00 6c 69 6d 69 74 73 2e 68 74 6d 6c 22 3e 6c 69 6d  limits.html">lim
11f10 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e 20 66 6f 72  its.html</a> for
11f20 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
11f30 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
11f40 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
11f50 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
11f60 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
11f70 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
11f80 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f 75 74 69  n those.** routi
11f90 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
11fa0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
11fb0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
11fc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
11fd0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70 61 72 61  s.** in the para
11fe0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
11ff0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
12000 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
12010 62 79 74 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  bytes in the.** 
12020 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
12030 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
12040 74 65 72 73 2e 20 20 54 68 65 20 6e 75 6d 62 65  ters.  The numbe
12050 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 64 6f  r.** of bytes do
12060 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
12070 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
12080 6f 72 20 61 74 20 74 68 65 20 65 6e 64 20 6f 66  or at the end of
12090 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20   strings..** If 
120a0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
120b0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
120c0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
120d0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
120e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
120f0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
12100 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
12110 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
12120 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
12130 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
12140 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
12150 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
12160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
12170 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
12180 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
12190 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
121a0 20 6f 72 0a 2a 2a 20 74 65 78 74 20 61 66 74 65   or.** text afte
121b0 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
121c0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
121d0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
121e0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
121f0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
12200 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
12210 68 65 6e 20 74 68 65 20 6c 69 62 72 61 72 79 20  hen the library 
12220 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
12230 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
12240 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
12250 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
12260 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
12270 74 6f 20 62 65 20 66 72 65 65 64 2e 20 20 49 66  to be freed.  If
12280 20 74 68 65 0a 2a 2a 20 66 69 66 74 68 20 61 72   the.** fifth ar
12290 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
122a0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
122b0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 20 53 51  NSIENT], then SQ
122c0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 0a 2a  Lite makes its.*
122d0 2a 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  * own private co
122e0 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
122f0 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
12300 72 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  re the sqlite3_b
12310 69 6e 64 5f 2a 28 29 0a 2a 2a 20 72 6f 75 74 69  ind_*().** routi
12320 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
12330 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * The sqlite3_bi
12340 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
12350 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
12360 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 6e 20 74  OB of length n t
12370 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
12380 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
12390 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
123a0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
123b0 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
123c0 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
123d0 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68 69 6c  ld it size) whil
123e0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
123f0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
12400 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
12410 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
12420 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f 72  lace-holders for
12430 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
12440 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
12450 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 20 0a   written using .
12460 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
12470 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
12480 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  t BLOB I/O] rout
12490 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
124a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
124b0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
124c0 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a  e called after.*
124d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
124e0 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74  re_v2()] (and it
124f0 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b  s variants) or [
12500 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
12510 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b   and.** before [
12520 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
12530 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65  .** Bindings are
12540 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
12550 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
12560 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
12570 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65  * Unbound parame
12580 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
12590 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
125a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
125b0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
125c0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
125d0 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64   or an error cod
125e0 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67  e if.** anything
125f0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53   goes wrong.  [S
12600 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
12610 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
12620 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
12630 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
12640 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ge.  [SQLITE_NOM
12650 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
12660 69 66 20 6d 61 6c 6c 6f 63 20 66 61 69 6c 73 2e  if malloc fails.
12670 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
12680 53 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  SE] is returned 
12690 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  if these routine
126a0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20  s are called on 
126b0 61 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  a virtual.** mac
126c0 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 65  hine that is the
126d0 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20   wrong state or 
126e0 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 64  which has alread
126f0 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  y been finalized
12700 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12710 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
12720 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
12730 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
12740 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
12750 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
12760 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
12770 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
12780 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
12790 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
127a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
127b0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
127c0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
127d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
127e0 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
127f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
12800 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
12810 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
12820 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
12830 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
12840 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
12850 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  ar*, int n, void
12860 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
12870 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
12880 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
12890 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
128a0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
128b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
128c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
128d0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
128e0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
128f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
12900 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
12910 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
12920 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
12930 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
12940 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 48  REF: Number Of H
12950 6f 73 74 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  ost Parameters.*
12960 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
12970 6c 61 72 67 65 73 74 20 68 6f 73 74 20 70 61 72  largest host par
12980 61 6d 65 74 65 72 20 69 6e 64 65 78 20 69 6e 20  ameter index in 
12990 74 68 65 20 70 72 65 63 6f 6d 70 69 6c 65 64 20  the precompiled 
129a0 73 74 61 74 65 6d 65 6e 74 20 67 69 76 65 6e 0a  statement given.
129b0 2a 2a 20 61 73 20 74 68 65 20 61 72 67 75 6d 65  ** as the argume
129c0 6e 74 2e 20 20 57 68 65 6e 20 74 68 65 20 68 6f  nt.  When the ho
129d0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  st parameters ar
129e0 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 20 6c  e of the forms l
129f0 69 6b 65 20 22 3a 41 41 41 22 0a 2a 2a 20 6f 72  ike ":AAA".** or
12a00 20 22 3f 22 2c 20 74 68 65 6e 20 74 68 65 79 20   "?", then they 
12a10 61 72 65 20 61 73 73 69 67 6e 65 64 20 73 65 71  are assigned seq
12a20 75 65 6e 74 69 61 6c 20 69 6e 63 72 65 61 73 69  uential increasi
12a30 6e 67 20 6e 75 6d 62 65 72 73 20 62 65 67 69 6e  ng numbers begin
12a40 6e 69 6e 67 0a 2a 2a 20 77 69 74 68 20 6f 6e 65  ning.** with one
12a50 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72  , so the value r
12a60 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
12a70 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74  umber of paramet
12a80 65 72 73 2e 20 20 48 6f 77 65 76 65 72 0a 2a 2a  ers.  However.**
12a90 20 69 66 20 74 68 65 20 73 61 6d 65 20 68 6f 73   if the same hos
12aa0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
12ab0 20 69 73 20 75 73 65 64 20 6d 75 6c 74 69 70 6c   is used multipl
12ac0 65 20 74 69 6d 65 73 2c 20 65 61 63 68 20 6f 63  e times, each oc
12ad0 63 75 72 72 61 6e 63 65 0a 2a 2a 20 69 73 20 67  currance.** is g
12ae0 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 75  iven the same nu
12af0 6d 62 65 72 2c 20 73 6f 20 74 68 65 20 76 61 6c  mber, so the val
12b00 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74  ue returned in t
12b10 68 61 74 20 63 61 73 65 20 69 73 20 74 68 65 20  hat case is the 
12b20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 75 6e 69  number.** of uni
12b30 71 75 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74  que host paramet
12b40 65 72 20 6e 61 6d 65 73 2e 20 20 49 66 20 68 6f  er names.  If ho
12b50 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  st parameters of
12b60 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
12b70 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 28 77 68  .** are used (wh
12b80 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e  ere NNN is an in
12b90 74 65 67 65 72 29 20 74 68 65 6e 20 74 68 65 72  teger) then ther
12ba0 65 20 6d 69 67 68 74 20 62 65 20 67 61 70 73 20  e might be gaps 
12bb0 69 6e 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  in the.** number
12bc0 69 6e 67 20 61 6e 64 20 74 68 65 20 76 61 6c 75  ing and the valu
12bd0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
12be0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
12bf0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
12c00 0a 2a 2a 20 68 6f 73 74 20 70 61 72 61 6d 65 74  .** host paramet
12c10 65 72 20 77 69 74 68 20 74 68 65 20 6c 61 72 67  er with the larg
12c20 65 73 74 20 69 6e 64 65 78 20 76 61 6c 75 65 2e  est index value.
12c30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 70 61  .**.** The prepa
12c40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6d 75  red statement mu
12c50 73 74 20 6e 6f 74 20 62 65 20 5b 73 71 6c 69 74  st not be [sqlit
12c60 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
12c70 6e 61 6c 69 7a 65 64 5d 0a 2a 2a 20 70 72 69 6f  nalized].** prio
12c80 72 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  r to this routin
12c90 65 20 72 65 74 75 72 6e 6e 69 6e 67 2e 20 20 4f  e returnning.  O
12ca0 74 68 65 72 77 69 73 65 20 74 68 65 20 72 65 73  therwise the res
12cb0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
12cc0 65 64 0a 2a 2a 20 61 6e 64 20 70 72 6f 62 61 62  ed.** and probab
12cd0 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
12ce0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
12cf0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
12d00 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
12d10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
12d20 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
12d30 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
12d40 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
12d50 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
12d60 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f  er to the name o
12d70 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d  f the n-th param
12d80 65 74 65 72 20 69 6e 20 61 20 0a 2a 2a 20 5b 73  eter in a .** [s
12d90 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72  qlite3_stmt | pr
12da0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12db0 5d 2e 0a 2a 2a 20 48 6f 73 74 20 70 61 72 61 6d  ]..** Host param
12dc0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
12dd0 6d 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  m ":AAA" or "@AA
12de0 41 22 20 6f 72 20 22 24 56 56 56 22 20 68 61 76  A" or "$VVV" hav
12df0 65 20 61 20 6e 61 6d 65 0a 2a 2a 20 77 68 69 63  e a name.** whic
12e00 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
12e10 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
12e20 20 6f 72 20 22 24 56 56 56 22 2e 20 20 0a 2a 2a   or "$VVV".  .**
12e30 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12e40 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
12e50 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 0a 2a   or "$" or "@".*
12e60 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
12e70 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
12e80 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73  e..** Parameters
12e90 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
12ea0 20 6f 72 20 22 3f 4e 4e 4e 22 20 68 61 76 65 20   or "?NNN" have 
12eb0 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54  no name..**.** T
12ec0 68 65 20 66 69 72 73 74 20 62 6f 75 6e 64 20 70  he first bound p
12ed0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
12ee0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
12ef0 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
12f00 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f  value n is out o
12f10 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
12f20 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
12f30 20 69 73 20 6e 61 6d 65 6c 65 73 73 2c 0a 2a 2a   is nameless,.**
12f40 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
12f50 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74  turned.  The ret
12f60 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
12f70 61 6c 77 61 79 73 20 69 6e 20 74 68 65 0a 2a 2a  always in the.**
12f80 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
12f90 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
12fa0 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 20  d parameter was 
12fb0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
12fc0 66 69 65 64 0a 2a 2a 20 61 73 20 55 54 46 2d 31  fied.** as UTF-1
12fd0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
12fe0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 20 5b 73  epare16()] or [s
12ff0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
13000 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  _v2()]..*/.const
13010 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
13020 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
13030 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
13040 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
13050 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
13060 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
13070 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
13080 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
13090 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ne returns the i
130a0 6e 64 65 78 20 6f 66 20 61 20 68 6f 73 74 20 70  ndex of a host p
130b0 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 74 68  arameter with th
130c0 65 20 67 69 76 65 6e 20 6e 61 6d 65 2e 0a 2a 2a  e given name..**
130d0 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 20 6d   The name must m
130e0 61 74 63 68 20 65 78 61 63 74 6c 79 2e 20 20 49  atch exactly.  I
130f0 66 20 6e 6f 20 70 61 72 61 6d 65 74 65 72 20 77  f no parameter w
13100 69 74 68 20 74 68 65 20 67 69 76 65 6e 20 6e 61  ith the given na
13110 6d 65 20 69 73 20 0a 2a 2a 20 66 6f 75 6e 64 2c  me is .** found,
13120 20 72 65 74 75 72 6e 20 30 2e 20 20 50 61 72 61   return 0.  Para
13130 6d 65 74 65 72 20 6e 61 6d 65 73 20 6d 75 73 74  meter names must
13140 20 62 65 20 55 54 46 38 2e 0a 2a 2f 0a 69 6e 74   be UTF8..*/.int
13150 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
13160 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
13170 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
13180 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
13190 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
131a0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
131b0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
131c0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
131d0 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  ** Contrary to t
131e0 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
131f0 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
13200 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
13210 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20 5b 73  .** reset the [s
13220 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
13230 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
13240 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  a .** [sqlite3_s
13250 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73  tmt | prepared s
13260 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73 65 20  tatement].  Use 
13270 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 0a  this routine to.
13280 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  ** reset all hos
13290 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
132a0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
132b0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
132c0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
132d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
132e0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
132f0 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
13300 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 52 65 74  lt Set.**.** Ret
13310 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
13320 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
13330 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
13340 72 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  rned by the .** 
13350 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
13360 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
13370 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f  tement]. This ro
13380 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 0a  utine returns 0.
13390 2a 2a 20 69 66 20 70 53 74 6d 74 20 69 73 20 61  ** if pStmt is a
133a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
133b0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
133c0 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 0a  turn data (for .
133d0 2a 2a 20 65 78 61 6d 70 6c 65 20 61 6e 20 55 50  ** example an UP
133e0 44 41 54 45 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71  DATE)..*/.int sq
133f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
13400 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
13410 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
13420 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
13430 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
13440 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 54 68 65  lt Set.**.** The
13450 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
13460 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
13470 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
13480 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
13490 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
134a0 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
134b0 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c  tement.  The sql
134c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
134d0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
134e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
134f0 72 20 74 6f 20 61 20 55 54 46 38 20 73 74 72 69  r to a UTF8 stri
13500 6e 67 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ng and sqlite3_c
13510 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a  olumn_name16().*
13520 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
13530 74 65 72 20 74 6f 20 61 20 55 54 46 31 36 20 73  ter to a UTF16 s
13540 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73  tring.  The firs
13550 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
13560 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
13570 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73  tmt | prepared s
13580 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
13590 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 53 45  mplements the SE
135a0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
135b0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
135c0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 63  rameter is the c
135d0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54  olumn number.  T
135e0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
135f0 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72  umn is.** number
13600 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65   0..**.** The re
13610 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
13620 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
13630 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
13640 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
13650 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
13660 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
13670 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
13680 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
13690 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
136a0 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  t call sqlite3_c
136b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
136c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
136d0 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e 20 74 68  ame16().** on th
136e0 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
136f0 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  *.** If sqlite3_
13700 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
13710 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
13720 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
13730 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
13740 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
13750 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
13760 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
13770 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
13780 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
13790 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
137a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
137b0 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
137c0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
137d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
137e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
137f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
13800 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
13810 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
13820 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
13830 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
13840 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
13850 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
13860 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74  o determine what
13870 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a   column of what.
13880 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63  ** table in whic
13890 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73  h database a res
138a0 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20  ult of a SELECT 
138b0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20  statement comes 
138c0 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d  from..** The nam
138d0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
138e0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
138f0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
13900 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
13910 72 20 61 20 55 54 46 38 20 6f 72 20 55 54 46 31  r a UTF8 or UTF1
13920 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f  6 string.  The _
13930 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
13940 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
13950 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
13960 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
13970 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
13980 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
13990 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
139a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
139b0 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
139c0 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
139d0 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
139e0 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 73 71  until.** the [sq
139f0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
13a00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
13a10 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73   is destroyed us
13a20 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
13a30 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
13a40 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
13a50 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
13a60 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
13a70 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
13a80 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  ncoding..**.** T
13a90 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
13aa0 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
13ab0 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
13ac0 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
13ad0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
13ae0 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
13af0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13b00 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f  ent to the follo
13b10 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20  wing calls is a 
13b20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
13b30 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  t | compiled SQL
13b40 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
13b50 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
13b60 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
13b70 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
13b80 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
13b90 20 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61 74   by .** the stat
13ba0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
13bb0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
13bc0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
13bd0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68  **.** If the Nth
13be0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
13bf0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
13c00 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
13c10 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65 72  on.** or subquer
13c20 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
13c30 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
13c40 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
13c50 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75  unctions.** retu
13c60 72 6e 20 4e 55 4c 4c 2e 20 4f 74 68 65 72 77 69  rn NULL. Otherwi
13c70 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
13c80 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  the .** name of 
13c90 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
13ca0 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64  abase, table and
13cb0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
13cc0 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  ry result.** col
13cd0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
13ce0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73  d from..**.** As
13cf0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
13d00 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
13d10 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74  se postfixed wit
13d20 68 20 22 31 36 22 20 72 65 74 75 72 6e 20 55 54  h "16" return UT
13d30 46 2d 31 36 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  F-16.** encoded 
13d40 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68  strings, the oth
13d50 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
13d60 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
13d70 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20   These APIs are 
13d80 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
13d90 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
13da0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
13db0 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45  the .** SQLITE_E
13dc0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
13dd0 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73  ADATA preprocess
13de0 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
13df0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
13e00 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
13e10 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
13e20 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
13e30 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
13e40 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
13e50 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
13e60 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
13e70 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
13e80 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
13e90 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
13ea0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
13eb0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
13ec0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
13ed0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
13ee0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
13ef0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
13f00 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
13f10 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
13f20 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
13f30 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
13f40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
13f50 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
13f60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
13f70 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
13f80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
13f90 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
13fa0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
13fb0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
13fc0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
13fd0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
13fe0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
13ff0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
14000 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
14010 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
14020 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
14030 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
14040 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
14050 65 74 65 72 20 69 73 20 61 20 5b 73 71 6c 69 74  eter is a [sqlit
14060 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c  e3_stmt | compil
14070 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
14080 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  ]. .** If this s
14090 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45  tatement is a SE
140a0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61  LECT statement a
140b0 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
140c0 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74  n of the .** ret
140d0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
140e0 20 20 6f 66 20 74 68 61 74 20 53 45 4c 45 43 54    of that SELECT
140f0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
14100 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
14110 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
14120 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
14130 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
14140 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
14150 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
14160 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   If the Nth colu
14170 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
14180 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
14190 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
141a0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
141b0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
141c0 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65  urned..** The re
141d0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
141e0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
141f0 63 6f 64 65 64 2e 20 46 6f 72 20 65 78 61 6d 70  coded. For examp
14200 6c 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 64 61  le, in.** the da
14210 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
14220 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
14230 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
14240 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20  ;.**.** And the 
14250 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
14260 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a  ent compiled:.**
14270 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
14280 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
14290 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 69 73 20 72  *.** Then this r
142a0 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
142b0 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
142c0 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
142d0 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c   second.** resul
142e0 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  t column (i==1),
142f0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
14300 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
14310 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  t result column.
14320 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ** (i==0)..**.**
14330 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
14340 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
14350 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62  ping.  So just b
14360 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
14370 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
14380 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
14390 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
143a0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
143b0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
143c0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
143d0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
143e0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
143f0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
14400 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
14410 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
14420 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54  c not static.  T
14430 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
14440 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
14450 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
14460 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
14470 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
14480 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
14490 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
144a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
144b0 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
144c0 33 5f 73 74 6d 74 20 2a 2c 20 69 6e 74 20 69 29  3_stmt *, int i)
144d0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
144e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
144f0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
14500 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20  stmt*,int);../* 
14510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
14520 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
14530 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41  tatement.**.** A
14540 66 74 65 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  fter an [sqlite3
14550 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61 74  _stmt | SQL stat
14560 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
14570 70 72 65 70 61 72 65 64 20 77 69 74 68 20 61 20  prepared with a 
14580 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65  call.** to eithe
14590 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
145a0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
145b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
145c0 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f  2()] or to one o
145d0 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20  f.** the legacy 
145e0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
145f0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
14600 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
14610 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  re16()],.** then
14620 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   this function m
14630 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
14640 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
14650 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
14660 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  .** statement..*
14670 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
14680 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
14690 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65 33   of this sqlite3
146a0 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
146b0 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
146c0 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
146d0 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
146e0 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
146f0 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
14700 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
14710 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
14720 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
14730 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
14740 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
14750 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
14760 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
14770 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
14780 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
14790 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
147a0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
147b0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
147c0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
147d0 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
147e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
147f0 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
14800 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
14810 2a 2a 20 49 6e 20 74 68 65 20 6c 61 67 61 63 79  ** In the lagacy
14820 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
14830 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
14840 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
14850 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b  ITE_BUSY], .** [
14860 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
14870 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
14880 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
14890 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
148a0 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22  ** With the "v2"
148b0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
148c0 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51  of the other [SQ
148d0 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
148e0 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51   code].** or [SQ
148f0 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
14900 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
14910 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65  t code] might be
14920 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
14930 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  well..**.** [SQL
14940 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
14950 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
14960 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
14970 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
14980 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
14990 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
149a0 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66   do its job.  If
149b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
149c0 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72  s a COMMIT.** or
149d0 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
149e0 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
149f0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
14a00 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
14a10 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
14a20 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
14a30 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d  nt is not a COMM
14a40 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  IT and occurs wi
14a50 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63  thin a.** explic
14a60 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
14a70 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
14a80 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
14a90 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
14aa0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
14ab0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
14ac0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
14ad0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
14ae0 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
14af0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
14b00 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
14b10 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
14b20 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
14b30 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
14b40 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
14b50 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
14b60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
14b70 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
14b80 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
14b90 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
14ba0 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
14bb0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
14bc0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
14bd0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
14be0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a  y data, then .**
14bf0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73   [SQLITE_ROW] is
14c00 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
14c10 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
14c20 20 64 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a   data is ready.*
14c30 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  * for processing
14c40 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   by the caller. 
14c50 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
14c60 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
14c70 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
14c80 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f  _column_int | co
14c90 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
14ca0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
14cb0 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
14cc0 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
14cd0 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
14ce0 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a  ow of data..** .
14cf0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
14d00 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
14d10 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
14d20 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
14d30 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
14d40 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
14d50 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
14d60 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
14d70 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
14d80 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
14d90 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
14da0 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
14db0 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
14dc0 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  g()]..** With th
14dd0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
14de0 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
14df0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
14e00 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c  example:.** [SQL
14e10 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
14e20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
14e30 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
14e40 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
14e50 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
14e60 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
14e70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
14e80 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   on the.** [sqli
14e90 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61  te3_stmt | prepa
14ea0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
14eb0 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
14ec0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
14ed0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
14ee0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
14ef0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
14f00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
14f10 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
14f20 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
14f30 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
14f40 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
14f50 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
14f60 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
14f70 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 73 71 6c  called on a [sql
14f80 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
14f90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
14fa0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
14fb0 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
14fc0 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
14fd0 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
14fe0 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20 70  e that had .** p
14ff0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
15000 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
15010 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
15020 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
15030 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
15040 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
15050 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15060 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
15070 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
15080 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
15090 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
150a0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  time..**.** <b>G
150b0 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
150c0 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20  lert:</b>.** In 
150d0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
150e0 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73 71  face, .** the sq
150f0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41 50 49  lite3_step() API
15100 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
15110 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
15120 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  code,.** [SQLITE
15130 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
15140 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74 68  ng any error oth
15150 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
15160 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51  BUSY].** and [SQ
15170 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
15180 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73 71  ou must call [sq
15190 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
151a0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
151b0 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
151c0 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
151d0 66 20 74 68 65 20 73 70 65 63 69 66 69 63 0a 2a  f the specific.*
151e0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  * [SQLITE_ERROR 
151f0 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  | result codes] 
15200 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
15210 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
15220 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
15230 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
15240 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
15250 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
15260 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
15270 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
15280 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
15290 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
152a0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
152b0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
152c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
152d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
152e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
152f0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
15300 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
15310 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
15320 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15330 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  e16()], then the
15340 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69 66   .** more specif
15350 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
15360 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
15370 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
15380 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
15390 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
153a0 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
153b0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
153c0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69  ecommended..*/.i
153d0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
153e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
153f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15400 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
15410 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75  e number of valu
15420 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  es in the curren
15430 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
15440 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 41  ult set..**.** A
15450 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b  fter a call to [
15460 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
15470 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51  that returns [SQ
15480 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 69 73 20  LITE_ROW], this 
15490 72 6f 75 74 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20  routine.** will 
154a0 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
154b0 76 61 6c 75 65 20 61 73 20 74 68 65 20 5b 73 71  value as the [sq
154c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
154d0 6e 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a  nt()] function..
154e0 2a 2a 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65  ** After [sqlite
154f0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
15500 74 75 72 6e 65 64 20 61 6e 20 5b 53 51 4c 49 54  turned an [SQLIT
15510 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
15520 5f 42 55 53 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20  _BUSY], or.** a 
15530 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
15540 65 72 72 6f 72 20 63 6f 64 65 5d 2c 20 6f 72 20  error code], or 
15550 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
15560 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
15570 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 20 74   .** called on t
15580 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
15590 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
155a0 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66  ement] for the f
155b0 69 72 73 74 20 74 69 6d 65 2c 0a 2a 2a 20 74 68  irst time,.** th
155c0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
155d0 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20  ns zero..*/.int 
155e0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
155f0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
15600 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
15610 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
15620 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
15630 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 76 61 6c 75  **.** Every valu
15640 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
15650 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
15660 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
15670 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
15680 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
15690 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
156a0 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
156b0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
156c0 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
156d0 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
156e0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
156f0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
15700 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
15710 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
15720 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
15730 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
15740 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
15750 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
15760 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
15770 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
15780 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
15790 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
157a0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
157b0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
157c0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
157d0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
157e0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
157f0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
15800 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c  _TEXT not.** SQL
15810 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
15820 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
15830 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
15840 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
15850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15860 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
15870 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
15880 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
15890 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
158a0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
158b0 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
158c0 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
158d0 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
158e0 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
158f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15900 52 65 73 75 6c 74 73 20 56 61 6c 75 65 73 20 46  Results Values F
15910 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 0a 2a  rom A Query.**.*
15920 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
15930 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
15940 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73  ion about.** a s
15950 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
15960 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75  the current resu
15970 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
15980 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20  y.  In every.** 
15990 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
159a0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
159b0 6e 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  nter to the .** 
159c0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
159d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  SQL statement] t
159e0 68 61 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20  hat is being.** 
159f0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
15a00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 74  sqlite3_stmt*] t
15a10 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
15a20 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
15a30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
15a40 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
15a50 61 72 69 61 6e 74 73 29 20 61 6e 64 0a 2a 2a 20  ariants) and.** 
15a60 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15a70 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
15a80 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
15a90 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
15aa0 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  tion .** should 
15ab0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  be returned.  Th
15ac0 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
15ad0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
15ae0 20 73 65 74 0a 2a 2a 20 68 61 73 20 61 6e 20 69   set.** has an i
15af0 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a  ndex of 0..**.**
15b00 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
15b10 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 75 72  ement is not cur
15b20 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
15b30 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
15b40 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 63 6f  if the.** the co
15b50 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
15b60 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
15b70 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
15b80 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73 65 20 72  ned. .** These r
15b90 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
15ba0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
15bb0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
15bc0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
15bd0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
15be0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
15bf0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
15c00 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
15c10 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
15c20 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
15c30 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 20 73 75  has been call su
15c40 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
15c50 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
15c60 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
15c70 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
15c80 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
15c90 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
15ca0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
15cb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
15cc0 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
15cd0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
15ce0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
15cf0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
15d00 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
15d10 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
15d20 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
15d30 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
15d40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
15d50 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
15d60 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
15d70 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
15d80 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
15d90 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
15da0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
15db0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
15dc0 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ed.  .**.** The 
15dd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
15de0 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
15df0 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
15e00 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
15e10 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
15e20 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
15e30 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
15e40 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54  esult column.  T
15e50 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
15e60 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
15e70 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
15e80 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
15e90 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
15ea0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
15eb0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
15ec0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
15ed0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
15ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
15ef0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
15f00 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
15f10 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
15f20 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
15f30 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
15f40 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
15f50 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
15f60 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
15f70 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
15f80 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
15f90 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
15fa0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
15fb0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
15fc0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
15fd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
15fe0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
15ff0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
16000 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  sion..**.** If t
16010 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
16020 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
16030 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
16040 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
16050 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  s() .** routine 
16060 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
16070 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
16080 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
16090 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  ng..** If the re
160a0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
160b0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
160c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
160d0 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
160e0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
160f0 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
16100 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
16110 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66   of bytes..** If
16120 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
16130 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
16140 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
16150 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
16160 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
16170 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
16180 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
16190 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
161a0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
161b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
161c0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
161d0 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  g..** The value 
161e0 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
161f0 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
16200 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74  ro terminator at
16210 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
16220 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20  he string.  For 
16230 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
16240 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
16250 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
16260 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
16270 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
16280 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
16290 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
162a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
162b0 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73  s16() routine is
162c0 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69   similar to sqli
162d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
162e0 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73  ().** but leaves
162f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55   the result in U
16300 54 46 2d 31 36 20 69 6e 73 74 65 61 64 20 6f 66  TF-16 instead of
16310 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65   UTF-8.  .** The
16320 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
16330 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
16340 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
16350 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
16360 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
16370 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
16380 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
16390 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ate.  For.** exa
163a0 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
163b0 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
163c0 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
163d0 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
163e0 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
163f0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
16400 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
16410 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20 74  ternally to do t
16420 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  he conversion.**
16430 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
16440 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
16450 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
16460 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68 61   conversions tha
16470 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c 69 65 64  t.** are applied
16480 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
16490 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
164a0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
164b0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
164c0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
164d0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
164e0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
164f0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
16500 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
16510 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
16520 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
16530 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
16540 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
16550 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
16560 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
16570 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
16580 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
16590 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
165a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
165b0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
165c0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
165d0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
165e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
165f0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
16600 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
16610 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
16620 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
16630 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
16640 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
16650 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
16660 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
16670 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
16680 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
16690 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66    <td> Same as f
166a0 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  or INTEGER->TEXT
166b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
166c0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
166d0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
166e0 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
166f0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
16700 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
16710 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
16720 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
16730 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
16740 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
16750 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
16760 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
16770 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
16780 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
16790 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
167a0 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
167b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
167c0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
167d0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
167e0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
167f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
16800 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
16810 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
16820 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
16830 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
16840 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
16850 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
16860 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
16870 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
16880 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
16890 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
168a0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
168b0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
168c0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
168d0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
168e0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
168f0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
16900 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
16910 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
16920 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
16930 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
16940 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
16950 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
16960 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
16970 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
16980 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
16990 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
169a0 74 73 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c  ts.** on equaval
169b0 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
169c0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
169d0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
169e0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
169f0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
16a00 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
16a10 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
16a20 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
16a30 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
16a40 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
16a50 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
16a60 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
16a70 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
16a80 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
16a90 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
16aa0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
16ab0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
16ac0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
16ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
16ae0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
16af0 6c 69 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70  lidated. .** Typ
16b00 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
16b10 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
16b20 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
16b30 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
16b40 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
16b50 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
16b60 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61  ><p>  The initia
16b70 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
16b80 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
16b90 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a  column_text() .*
16ba0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 73 71  *          or sq
16bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
16bc0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
16bd0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
16be0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
16bf0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
16c00 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
16c10 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a  ring.</p></li>.*
16c20 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68  *.** <li><p>  Th
16c30 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
16c40 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
16c50 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
16c60 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
16c70 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69  **          sqli
16c80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
16c90 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
16ca0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
16cb0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
16cc0 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46            to UTF
16cd0 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a  -16.</p></li>.**
16ce0 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
16cf0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
16d00 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
16d10 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
16d20 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
16d30 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
16d40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
16d50 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
16d60 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
16d70 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
16d80 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
16d90 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  /p></li>.** </ul
16da0 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69  >.**.** Conversi
16db0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
16dc0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
16dd0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
16de0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
16df0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
16e00 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
16e10 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
16e20 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
16e30 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
16e40 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
16e50 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
16e60 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
16e70 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
16e80 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
16e90 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
16ea0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
16eb0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
16ec0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69  , but sometime i
16ed0 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73  t is.** not poss
16ee0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
16ef0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
16f00 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
16f10 69 64 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20  idated.  .**.** 
16f20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
16f30 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
16f40 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
16f50 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
16f60 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
16f70 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
16f80 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75   ways:.**.**  <u
16f90 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
16fa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
16fb0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
16fc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
16fd0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
16fe0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
16ff0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
17000 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
17010 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
17020 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
17030 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
17040 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
17050 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
17060 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75  6()</li>.**  </u
17070 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
17080 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
17090 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
170a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
170b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
170c0 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c  lob(),.** or sql
170d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
170e0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
170f0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 20 69  rce the result i
17100 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a  nto the desired.
17110 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ** format, then 
17120 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
17130 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
17140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
17150 62 79 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20  bytes16() to.** 
17160 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
17170 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
17180 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f   not mix call to
17190 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
171a0 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  text() or.** sql
171b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
171c0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
171d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
171e0 62 79 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20  bytes16().  And 
171f0 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61  do not.** mix ca
17200 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
17210 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77  olumn_text16() w
17220 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
17230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
17240 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  s()..**.** The p
17250 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
17260 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
17270 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
17280 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
17290 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
172a0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
172b0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
172c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
172d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
172e0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
172f0 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72  lled.  The memor
17300 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
17310 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
17320 61 6e 64 20 62 6c 6f 62 73 20 69 73 20 66 72 65  and blobs is fre
17330 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
17340 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
17350 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
17360 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
17370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
17380 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 5f  lob()], [sqlite_
17390 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
173a0 65 74 63 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73  etc. into .** [s
173b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
173c0 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72  **.** If a memor
173d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
173e0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
173f0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
17400 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
17410 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
17420 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
17430 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
17440 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
17450 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
17460 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
17470 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
17480 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
17490 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
174a0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
174b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
174c0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
174d0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
174e0 4d 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  MEM]..*/.const v
174f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
17500 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
17510 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
17520 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
17530 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
17540 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
17550 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
17560 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
17570 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
17580 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
17590 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
175a0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
175b0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
175c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
175d0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
175e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
175f0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
17600 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
17610 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
17620 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
17630 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
17640 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
17650 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
17660 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
17670 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
17680 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
17690 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
176a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
176b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
176c0 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
176d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
176e0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
176f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
17700 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
17710 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
17720 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17730 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
17740 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
17750 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ect.**.** The sq
17760 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
17770 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
17780 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
17790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
177a0 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  t | compiled SQL
177b0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20   statement]. If 
177c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
177d0 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73 75  s.** executed su
177e0 63 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e  ccessfully, or n
177f0 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61  ot executed at a
17800 6c 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ll, then SQLITE_
17810 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  OK is returned..
17820 2a 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20  ** If execution 
17830 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
17840 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20   failed then an 
17850 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
17860 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  R | error code] 
17870 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
17880 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
17890 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20   error code].** 
178a0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a  is returned. .**
178b0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
178c0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
178d0 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
178e0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
178f0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
17900 74 65 33 5f 73 74 6d 74 20 7c 20 76 69 72 74 75  te3_stmt | virtu
17910 61 6c 20 6d 61 63 68 69 6e 65 5d 2e 20 20 49 66  al machine].  If
17920 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63   the virtual mac
17930 68 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  hine has not .**
17940 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
17950 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72  tion when this r
17960 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
17970 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a  , that is like.*
17980 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61  * encountering a
17990 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e  n error or an in
179a0 74 65 72 72 75 70 74 2e 20 20 28 53 65 65 20 5b  terrupt.  (See [
179b0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
179c0 74 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d  t()].) .** Incom
179d0 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
179e0 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
179f0 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
17a00 73 20 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a  s cancelled,  .*
17a10 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
17a20 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
17a30 2c 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 53  , and the .** [S
17a40 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65  QLITE_ERROR | re
17a50 73 75 6c 74 20 63 6f 64 65 5d 20 72 65 74 75 72  sult code] retur
17a60 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c  ned will be [SQL
17a70 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69  ITE_ABORT]..*/.i
17a80 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
17a90 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
17aa0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
17ab0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
17ac0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
17ad0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
17ae0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
17af0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
17b00 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
17b10 65 74 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  et a .** [sqlite
17b20 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65  3_stmt | compile
17b30 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d  d SQL statement]
17b40 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b   object..** back
17b50 20 74 6f 20 69 74 27 73 20 69 6e 69 74 69 61 6c   to it's initial
17b60 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
17b70 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
17b80 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74  .** Any SQL stat
17b90 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
17ba0 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
17bb0 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
17bc0 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
17bd0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
17be0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
17bf0 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
17c00 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
17c10 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
17c20 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
17c30 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
17c40 67 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  gs..*/.int sqlit
17c50 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
17c60 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
17c70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17c80 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
17c90 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
17ca0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
17cb0 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
17cc0 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
17cd0 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
17ce0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a   or aggregates.*
17cf0 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  * or to redefine
17d00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
17d10 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
17d20 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
17d30 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64  gates.  The.** d
17d40 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62  ifference only b
17d50 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69  etween the two i
17d60 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
17d70 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  d parameter, the
17d80 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
17d90 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f  (scalar) functio
17da0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
17db0 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  is encoded in UT
17dc0 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
17dd0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
17de0 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20  on() and UTF-16 
17df0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
17e00 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e  te_function16().
17e10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
17e20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
17e30 20 5b 73 71 6c 69 74 65 33 20 7c 20 64 61 74 61   [sqlite3 | data
17e40 62 61 73 65 20 68 61 6e 64 6c 65 5d 20 74 68 61  base handle] tha
17e50 74 20 68 6f 6c 64 73 20 74 68 65 0a 2a 2a 20 53  t holds the.** S
17e60 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
17e70 67 67 72 65 67 61 74 65 20 69 73 20 74 6f 20 62  ggregate is to b
17e80 65 20 61 64 64 65 64 20 6f 72 20 72 65 64 65 66  e added or redef
17e90 69 6e 65 64 2e 20 49 66 20 61 20 73 69 6e 67 6c  ined. If a singl
17ea0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
17eb0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
17ec0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
17ed0 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e  internally, then
17ee0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
17ef0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
17f00 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e  must be added in
17f10 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65 61  dividually to ea
17f20 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68  ch database.** h
17f30 61 6e 64 6c 65 20 77 69 74 68 20 77 68 69 63 68  andle with which
17f40 20 74 68 65 79 20 77 69 6c 6c 20 62 65 20 75 73   they will be us
17f50 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
17f60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
17f70 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
17f80 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
17f90 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20  o be created.** 
17fa0 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a  or redefined..**
17fb0 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   The length of t
17fc0 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
17fd0 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c  ed to 255 bytes,
17fe0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
17ff0 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69  e .** zero-termi
18000 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61  nator.  Note tha
18010 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74  t the name lengt
18020 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79  h limit is in by
18030 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72  tes, not.** char
18040 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74  acters.  Any att
18050 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
18060 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
18070 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
18080 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61  will result in a
18090 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65  n SQLITE_ERROR e
180a0 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rror..**.** The 
180b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
180c0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
180d0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
180e0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
180f0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
18100 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20   takes. If this 
18110 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
18120 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
18130 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
18140 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
18150 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
18160 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a   of arguments..*
18170 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
18180 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
18190 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
181a0 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  hat .** [SQLITE_
181b0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
181c0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
181d0 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
181e0 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
181f0 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20  eters.  Any SQL 
18200 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
18210 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  ntation should b
18220 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
18230 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d  * work with UTF-
18240 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
18250 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
18260 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
18270 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
18280 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
18290 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
182a0 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74  han another.  It
182b0 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a   is allowed to.*
182c0 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
182d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
182e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
182f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
18300 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
18310 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
18320 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
18330 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
18340 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
18350 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70  ..** When multip
18360 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
18370 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
18380 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
18390 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
183a0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
183b0 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
183c0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
183d0 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
183e0 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
183f0 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
18400 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
18410 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
18420 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65   care what.** te
18430 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  xt encoding is u
18440 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
18450 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
18460 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49  ould be.** [SQLI
18470 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54  TE_ANY]..**.** T
18480 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
18490 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
184a0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
184b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
184c0 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ** of the functi
184d0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
184e0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
184f0 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  er using.** [sql
18500 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
18510 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76  ]..**.** The sev
18520 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64  enth, eighth and
18530 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
18540 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
18550 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
18560 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
18570 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
18580 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
18590 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  nt the SQL.** fu
185a0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
185b0 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51  ate. A scalar SQ
185c0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
185d0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
185e0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20  ation of.** the 
185f0 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f  xFunc callback o
18600 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly, NULL pointe
18610 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  rs should be pas
18620 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
18630 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70  .** and xFinal p
18640 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67  arameters. An ag
18650 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
18660 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
18670 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
18680 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20  ** of xStep and 
18690 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
186a0 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
186b0 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64   for xFunc. To d
186c0 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73  elete an.** exis
186d0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
186e0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
186f0 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c  pass NULL for al
18700 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
18710 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  .** callback..**
18720 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74  .** It is permit
18730 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
18740 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
18750 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
18760 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
18770 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
18780 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
18790 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
187a0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
187b0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
187c0 69 6e 67 20 70 65 72 66 65 72 72 65 64 20 74 65  ing perferred te
187d0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53  xt encodings.  S
187e0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
187f0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
18800 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  tion most closel
18810 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
18820 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
18830 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
18840 73 20 75 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  s used..*/.int s
18850 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
18860 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
18870 33 20 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  3 *,.  const cha
18880 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
18890 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
188a0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
188b0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a  void*,.  void (*
188c0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
188d0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
188e0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
188f0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
18900 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
18910 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
18920 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
18930 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
18940 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
18950 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
18960 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
18970 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 76 6f  te3*,.  const vo
18980 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
18990 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
189a0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
189b0 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28   void*,.  void (
189c0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
189d0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
189e0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
189f0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
18a00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
18a10 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
18a20 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
18a30 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
18a40 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a  ontext*).);../*.
18a50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
18a60 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
18a70 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
18a80 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
18a90 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
18aa0 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
18ab0 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
18ac0 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
18ad0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
18ae0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
18af0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
18b00 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
18b10 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
18b20 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
18b30 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
18b40 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
18b50 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
18b60 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
18b70 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
18b80 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
18b90 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
18ba0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
18bb0 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
18bc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
18bd0 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
18be0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
18bf0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
18c00 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
18c10 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65  PI3REF: Obsolete
18c20 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
18c30 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
18c40 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73   are all now obs
18c50 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72  olete.  In order
18c60 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
18c70 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
18c80 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
18c90 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74  er code, we cont
18ca0 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a  inue to support.
18cb0 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ** these functio
18cc0 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ns.  However, ne
18cd0 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72  w development pr
18ce0 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76  ojects should av
18cf0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
18d00 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
18d10 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
18d20 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
18d30 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
18d40 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
18d50 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
18d60 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e   to tell you wan
18d70 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e  t they do..*/.in
18d80 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
18d90 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
18da0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74  3_context*);.int
18db0 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
18dc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
18dd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61  .int sqlite3_tra
18de0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
18df0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
18e00 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e  lite3_stmt*);.in
18e10 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
18e20 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
18e30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
18e40 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
18e50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18e60 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
18e70 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
18e80 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a  eter Values.**.*
18e90 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
18ea0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
18eb0 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
18ec0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
18ed0 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
18ee0 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
18ef0 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
18f00 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
18f10 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
18f20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
18f30 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
18f40 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
18f50 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
18f60 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
18f70 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
18f80 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
18f90 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
18fa0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
18fb0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
18fc0 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
18fd0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
18fe0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
18ff0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
19000 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
19010 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
19020 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
19030 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
19040 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
19050 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
19060 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
19070 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
19080 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
19090 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
190a0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
190b0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
190c0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
190d0 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
190e0 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
190f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
19100 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
19110 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
19120 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
19130 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
19140 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
19150 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  lumn_blob | sqli
19160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75  te3_column_* rou
19170 74 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74 68  tines] except th
19180 61 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  at .** these rou
19190 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
191a0 67 6c 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  gle [sqlite3_val
191b0 75 65 2a 5d 20 70 6f 69 6e 74 65 72 20 69 6e 73  ue*] pointer ins
191c0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  tead.** of an [s
191d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
191e0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
191f0 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
19200 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
19210 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
19220 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
19230 78 74 72 61 63 74 73 20 61 20 55 54 46 31 36 20  xtracts a UTF16 
19240 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
19250 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
19260 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
19270 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20  achine.  The.** 
19280 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
19290 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
192a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
192b0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
192c0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 31  .** extract UTF1
192d0 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
192e0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
192f0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
19300 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  tively..**.** Th
19310 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
19320 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
19330 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
19340 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
19350 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
19360 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
19370 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
19380 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
19390 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
193a0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
193b0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
193c0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
193d0 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
193e0 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
193f0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
19400 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
19410 72 64 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66  rder.** words if
19420 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 6f 72   the value is or
19430 69 67 69 6e 61 6c 20 61 20 73 74 72 69 6e 67 20  iginal a string 
19440 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
19450 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
19460 6e 20 69 74 20 69 73 20 64 6f 6e 65 2e 20 20 4f  n it is done.  O
19470 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
19480 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20  ersion occurs.  
19490 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  The .** [SQLITE_
194a0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
194b0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
194c0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
194d0 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
194e0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
194f0 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
19500 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
19510 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  nter that.** is 
19520 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
19530 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
19540 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
19550 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
19560 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
19570 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
19580 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
19590 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
195a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
195b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
195c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
195d0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
195e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
195f0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
19600 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
19610 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  16()].  .**.** T
19620 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
19630 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
19640 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
19650 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
19660 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
19670 70 70 6c 69 65 64 20 74 68 65 20 73 71 6c 69 74  pplied the sqlit
19680 65 33 5f 76 61 6c 75 65 2a 20 70 61 72 61 6d 65  e3_value* parame
19690 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c 20 69 66 20  ters..** Or, if 
196a0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
196b0 65 2a 20 61 72 67 75 6d 65 6e 74 20 63 6f 6d 65  e* argument come
196c0 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
196d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
196e0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
196f0 2c 20 74 68 65 6e 20 74 68 65 73 65 20 72 6f 75  , then these rou
19700 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 20  tines should be 
19710 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
19720 73 61 6d 65 20 74 68 72 65 61 64 0a 2a 2a 20 74  same thread.** t
19730 68 61 74 20 72 61 6e 20 5b 73 71 6c 69 74 65 33  hat ran [sqlite3
19740 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
19750 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
19760 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
19770 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
19780 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
19790 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
197a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
197b0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
197c0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
197d0 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
197e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
197f0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
19800 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
19810 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
19820 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
19830 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
19840 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
19850 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
19860 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
19870 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
19880 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
19890 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
198a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
198b0 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
198c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
198d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
198e0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
198f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
19900 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
19910 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
19920 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
19930 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
19940 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
19950 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
19960 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
19970 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
19980 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
19990 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
199a0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
199b0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
199c0 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
199d0 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67  tation of aggreg
199e0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
199f0 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  s use this routi
19a00 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a  ne to allocate.*
19a10 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f  * a structure fo
19a20 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
19a30 73 74 61 74 65 2e 20 20 54 68 65 20 66 69 72 73  state.  The firs
19a40 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74  t time this rout
19a50 69 6e 65 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64  ine.** is called
19a60 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
19a70 72 20 61 67 67 72 65 67 61 74 65 2c 20 61 20 6e  r aggregate, a n
19a80 65 77 20 73 74 72 75 63 74 75 72 65 20 6f 66 20  ew structure of 
19a90 73 69 7a 65 20 6e 42 79 74 65 73 0a 2a 2a 20 69  size nBytes.** i
19aa0 73 20 61 6c 6c 6f 63 61 74 65 64 2c 20 7a 65 72  s allocated, zer
19ab0 6f 65 64 2c 20 61 6e 64 20 72 65 74 75 72 6e 65  oed, and returne
19ac0 64 2e 20 20 4f 6e 20 73 75 62 73 65 71 75 65 6e  d.  On subsequen
19ad0 74 20 63 61 6c 6c 73 20 28 66 6f 72 20 74 68 65  t calls (for the
19ae0 0a 2a 2a 20 73 61 6d 65 20 61 67 67 72 65 67 61  .** same aggrega
19af0 74 65 20 69 6e 73 74 61 6e 63 65 29 20 74 68 65  te instance) the
19b00 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
19b10 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 69  returned.  The i
19b20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
19b30 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
19b40 65 20 63 61 6e 20 75 73 65 20 74 68 65 20 72 65  e can use the re
19b50 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f  turned buffer to
19b60 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61   accumulate data
19b70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 66 66  ..**.** The buff
19b80 65 72 20 61 6c 6c 6f 63 61 74 65 64 20 69 73 20  er allocated is 
19b90 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
19ba0 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 77 68  lly by SQLite wh
19bb0 61 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  an the aggregate
19bc0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  .** query conclu
19bd0 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
19be0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73  irst parameter s
19bf0 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20  hould be a copy 
19c00 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  of the .** [sqli
19c10 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
19c20 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
19c30 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
19c40 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
19c50 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
19c60 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
19c70 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
19c80 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
19c90 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
19ca0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
19cb0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
19cc0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
19cd0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
19ce0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
19cf0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
19d00 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
19d10 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
19d20 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
19d30 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
19d40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19d50 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
19d60 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
19d70 20 54 68 65 20 70 55 73 65 72 44 61 74 61 20 70   The pUserData p
19d80 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19d90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
19da0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
19db0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
19dc0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
19dd0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65   routines.** use
19de0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 75 73  d to register us
19df0 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 69 73 20  er functions is 
19e00 61 76 61 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a 20  available to.** 
19e10 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
19e20 6f 6e 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  on of the functi
19e30 6f 6e 20 75 73 69 6e 67 20 74 68 69 73 20 63 61  on using this ca
19e40 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ll..**.** This r
19e50 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
19e60 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
19e70 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
19e80 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
19e90 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
19ea0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
19eb0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
19ec0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
19ed0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19ee0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
19ef0 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
19f00 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
19f10 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
19f20 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
19f30 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
19f40 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
19f50 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68 20   meta-data with 
19f60 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
19f70 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
19f80 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
19f90 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
19fa0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
19fb0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
19fc0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
19fd0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
19fe0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
19ff0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
1a000 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d 61  ted meta-data ma
1a010 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
1a020 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
1a030 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
1a040 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
1a050 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
1a060 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
1a070 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
1a080 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
1a090 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
1a0a0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
1a0b0 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64  red as.** meta-d
1a0c0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
1a0d0 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ith the SQL valu
1a0e0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
1a0f0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
1a100 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20  on.** pattern.  
1a110 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  The compiled reg
1a120 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
1a130 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
1a140 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
1a150 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
1a160 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f  same function so
1a170 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e   that the origin
1a180 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  al pattern strin
1a190 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65  g.** does not ne
1a1a0 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69  ed to be recompi
1a1b0 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f  led on each invo
1a1c0 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  cation..**.** Th
1a1d0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
1a1e0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
1a1f0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1a200 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 2d  ter to the meta-
1a210 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
1a220 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  ed with the Nth 
1a230 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 20 74  argument value t
1a240 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 53 51  o the current SQ
1a250 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  L function.** ca
1a260 6c 6c 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ll, where N is t
1a270 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a280 74 65 72 2e 20 49 66 20 6e 6f 20 6d 65 74 61 2d  ter. If no meta-
1a290 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 73 65  data has been se
1a2a0 74 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 76 61  t for.** that va
1a2b0 6c 75 65 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  lue, then a NULL
1a2c0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
1a2d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
1a2e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
1a2f0 61 74 61 28 29 20 69 73 20 75 73 65 64 20 74 6f  ata() is used to
1a300 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d   associate meta-
1a310 64 61 74 61 20 77 69 74 68 20 61 6e 20 53 51 4c  data with an SQL
1a320 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  .** function arg
1a330 75 6d 65 6e 74 2e 20 54 68 65 20 74 68 69 72 64  ument. The third
1a340 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1a350 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
1a360 65 74 61 2d 64 61 74 61 0a 2a 2a 20 74 6f 20 62  eta-data.** to b
1a370 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
1a380 68 20 74 68 65 20 4e 74 68 20 75 73 65 72 20 66  h the Nth user f
1a390 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
1a3a0 20 76 61 6c 75 65 2e 20 54 68 65 20 66 6f 75 72   value. The four
1a3b0 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  th.** parameter 
1a3c0 73 70 65 63 69 66 69 65 73 20 61 20 64 65 73 74  specifies a dest
1a3d0 72 75 63 74 6f 72 20 74 68 61 74 20 77 69 6c 6c  ructor that will
1a3e0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   be called on th
1a3f0 65 20 6d 65 74 61 2d 0a 2a 2a 20 64 61 74 61 20  e meta-.** data 
1a400 70 6f 69 6e 74 65 72 20 74 6f 20 72 65 6c 65 61  pointer to relea
1a410 73 65 20 69 74 20 77 68 65 6e 20 69 74 20 69 73  se it when it is
1a420 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
1a430 72 65 64 2e 20 49 66 20 74 68 65 20 0a 2a 2a 20  red. If the .** 
1a440 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 4e 55  destructor is NU
1a450 4c 4c 2c 20 69 74 20 69 73 20 6e 6f 74 20 69 6e  LL, it is not in
1a460 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  voked..**.** In 
1a470 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d 64  practice, meta-d
1a480 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
1a490 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
1a4a0 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
1a4b0 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
1a4c0 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
1a4d0 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
1a4e0 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
1a4f0 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
1a500 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e  d SQL variables.
1a510 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1a520 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
1a530 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
1a540 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
1a550 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
1a560 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
1a570 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
1a580 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
1a590 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1a5a0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
1a5b0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
1a5c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1a5d0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 76  *, int, void*, v
1a5e0 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
1a5f0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
1a600 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
1a610 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
1a620 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
1a630 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
1a640 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
1a650 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
1a660 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
1a670 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
1a680 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
1a690 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
1a6a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
1a6b0 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20  lob()].  If the 
1a6c0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
1a6d0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
1a6e0 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
1a6f0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
1a700 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
1a710 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
1a720 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
1a730 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
1a740 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
1a750 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c  ed.  The .** SQL
1a760 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
1a770 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
1a780 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
1a790 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
1a7a0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
1a7b0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
1a7c0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
1a7d0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
1a7e0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
1a7f0 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
1a800 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
1a810 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
1a820 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
1a830 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
1a840 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
1a850 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
1a860 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
1a870 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
1a880 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
1a890 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
1a8a0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
1a8b0 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
1a8c0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
1a8d0 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
1a8e0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
1a8f0 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
1a900 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
1a910 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
1a920 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
1a930 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
1a940 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
1a950 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1a960 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
1a970 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
1a980 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
1a990 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
1a9a0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
1a9b0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
1a9c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
1a9d0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
1a9e0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
1a9f0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
1aa00 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
1aa10 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
1aa20 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
1aa30 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
1aa40 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a  uch like the .**
1aa50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1aa60 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
1aa70 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20  nd_*] family of 
1aa80 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a  functions used.*
1aa90 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  * to bind values
1aaa0 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
1aab0 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
1aac0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
1aad0 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  efer to the.** [
1aae0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1aaf0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
1ab00 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  _* documentation
1ab10 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  ] for.** additio
1ab20 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
1ab30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1ab40 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
1ab50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
1ab60 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
1ab70 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
1ab80 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
1ab90 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
1aba0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
1abb0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 70 61  tion.  The.** pa
1abc0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1abd0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
1abe0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
1abf0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
1ac00 20 69 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   is the text of 
1ac10 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1ac20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1ac30 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
1ac40 67 28 29 20 63 61 75 73 65 20 74 68 65 20 66 75  g() cause the fu
1ac50 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
1ac60 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 72 6f  ation.** to thro
1ac70 77 20 61 6e 64 20 65 72 72 6f 72 20 69 6e 64 69  w and error indi
1ac80 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
1ac90 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
1aca0 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65  to long.** to re
1acb0 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  present..**.** T
1acc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
1acd0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
1ace0 6d 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  m within the sam
1acf0 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
1ad00 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
1ad10 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1ad20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
1ad30 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2e 0a 2a  text] pointer..*
1ad40 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
1ad50 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
1ad60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
1ad70 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
1ad80 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1ad90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
1ada0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
1adb0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
1adc0 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
1add0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
1ade0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1adf0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
1ae00 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
1ae10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
1ae20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1ae30 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
1ae40 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
1ae50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
1ae60 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
1ae70 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
1ae80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1ae90 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
1aea0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
1aeb0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1aec0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
1aed0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
1aee0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1aef0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
1af00 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
1af10 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
1af20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
1af30 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
1af40 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
1af50 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
1af60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1af70 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
1af80 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1af90 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1afa0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
1afb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1afc0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1afd0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1afe0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1aff0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
1b000 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1b010 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1b020 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
1b030 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1b040 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
1b050 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1b060 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
1b070 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
1b080 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
1b090 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
1b0a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b0b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
1b0c0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1b0d0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
1b0e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b0f0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
1b100 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
1b110 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
1b120 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54  equences.**.** T
1b130 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
1b140 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e  re used to add n
1b150 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
1b160 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a  uences to the.**
1b170 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64   [sqlite3*] hand
1b180 6c 65 20 73 70 65 63 69 66 69 65 64 20 61 73 20  le specified as 
1b190 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1b1a0 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  nt. .**.** The n
1b1b0 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63  ame of the new c
1b1c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
1b1d0 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61  e is specified a
1b1e0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
1b1f0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
1b200 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1b210 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
1b220 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
1b230 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
1b240 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20  F-16 string for 
1b250 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1b260 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 20 49  ollation16().  I
1b270 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74  n all cases.** t
1b280 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65  he name is passe
1b290 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1b2a0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
1b2b0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  t..**.** The thi
1b2c0 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  rd argument must
1b2d0 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
1b2e0 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
1b2f0 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _UTF8],.** [SQLI
1b300 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b  TE_UTF16LE] or [
1b310 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
1b320 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
1b330 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69   the user-suppli
1b340 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78  ed.** routine ex
1b350 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73  pects to be pass
1b360 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ed pointers to s
1b370 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75  trings encoded u
1b380 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55  sing UTF-8,.** U
1b390 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
1b3a0 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69  ian or UTF-16 bi
1b3b0 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  g-endian respect
1b3c0 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 70  ively..**.** A p
1b3d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73  ointer to the us
1b3e0 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74  er supplied rout
1b3f0 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73  ine must be pass
1b400 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a  ed as the fifth.
1b410 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ** argument. If 
1b420 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73  it is NULL, this
1b430 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
1b440 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c  deleting the col
1b450 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
1b460 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69  ce (so that SQLi
1b470 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69  te cannot call i
1b480 74 20 61 6e 79 6d 6f 72 65 29 2e 20 45 61 63 68  t anymore). Each
1b490 20 74 69 6d 65 20 74 68 65 20 75 73 65 72 0a 2a   time the user.*
1b4a0 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  * supplied funct
1b4b0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
1b4c0 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20 63  it is passed a c
1b4d0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1b4e0 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
1b4f0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
1b500 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  t to sqlite3_cre
1b510 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
1b520 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  or.** sqlite3_cr
1b530 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
1b540 28 29 20 61 73 20 69 74 73 20 66 69 72 73 74 20  () as its first 
1b550 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1b560 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61   The remaining a
1b570 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
1b580 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20 72 6f  user-supplied ro
1b590 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
1b5a0 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
1b5b0 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
1b5c0 5b 6c 65 6e 67 74 68 2c 20 64 61 74 61 5d 20 70  [length, data] p
1b5d0 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
1b5e0 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
1b5f0 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
1b600 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
1b610 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
1b620 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
1b630 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
1b640 73 74 65 72 65 64 2e 20 54 68 65 20 75 73 65 72  stered. The user
1b650 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
1b660 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
1b670 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
1b680 65 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73  e if.** the firs
1b690 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
1b6a0 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
1b6b0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
1b6c0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73   the second.** s
1b6d0 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52  tring. i.e. (STR
1b6e0 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e  ING1 - STRING2).
1b6f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1b700 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1b710 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
1b720 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
1b730 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
1b740 2a 20 65 78 63 61 70 74 20 74 68 61 74 20 69 74  * excapt that it
1b750 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20   takes an extra 
1b760 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
1b770 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
1b780 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  or.** the collat
1b790 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75  ion.  The destru
1b7a0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77  ctor is called w
1b7b0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
1b7c0 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65  n is.** destroye
1b7d0 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20  d and is passed 
1b7e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f  a copy of the fo
1b7f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76  urth parameter v
1b800 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  oid* pointer.** 
1b810 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
1b820 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
1b830 76 32 28 29 2e 20 20 43 6f 6c 6c 61 74 69 6f 6e  v2().  Collation
1b840 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20  s are destroyed 
1b850 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65  when.** they are
1b860 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
1b870 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68  ater calls to th
1b880 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
1b890 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  tion functions.*
1b8a0 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 73  * or when the [s
1b8b0 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73  qlite3*] databas
1b8c0 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73  e handle is clos
1b8d0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1b8e0 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
1b8f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72  * The sqlite3_cr
1b900 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
1b910 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
1b920 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1b930 64 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  d.** subject to 
1b940 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1b950 20 72 65 6c 65 61 73 65 73 2e 20 20 54 68 65 20   releases.  The 
1b960 6f 74 68 65 72 20 63 6f 6c 6c 61 74 69 6f 6e 20  other collation 
1b970 63 72 65 61 74 69 6f 6e 0a 2a 2a 20 66 75 6e 63  creation.** func
1b980 74 69 6f 6e 73 20 61 72 65 20 73 74 61 62 6c 65  tions are stable
1b990 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1b9a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1b9b0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
1b9c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
1b9d0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
1b9e0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
1b9f0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
1ba00 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1ba10 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
1ba20 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
1ba30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1ba40 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
1ba50 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
1ba60 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
1ba70 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
1ba80 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
1ba90 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
1baa0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
1bab0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
1bac0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
1bad0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
1bae0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
1baf0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
1bb00 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
1bb10 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
1bb20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
1bb30 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
1bb40 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
1bb50 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
1bb60 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
1bb70 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
1bb80 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
1bb90 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
1bba0 73 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  s.**.** To avoid
1bbb0 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
1bbc0 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
1bbd0 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
1bbe0 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
1bbf0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
1bc00 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
1bc10 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
1bc20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
1bc30 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1bc40 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 6c  handle to be cal
1bc50 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  led whenever an 
1bc60 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
1bc70 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a  ion sequence is.
1bc80 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ** required..**.
1bc90 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69  ** If the functi
1bca0 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
1bcb0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1bcc0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1bcd0 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
1bce0 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
1bcf0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
1bd00 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
1bd10 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
1bd20 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
1bd30 20 69 6e 20 55 54 46 2d 38 2e 20 49 66 20 73 71   in UTF-8. If sq
1bd40 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
1bd50 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
1bd60 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a  ed, the names.**
1bd70 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
1bd80 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
1bd90 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1bda0 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65 69  er. A call to ei
1bdb0 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ther.** function
1bdc0 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78   replaces any ex
1bdd0 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e  isting callback.
1bde0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1bdf0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1be00 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
1be10 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
1be20 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
1be30 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1be40 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
1be50 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
1be60 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
1be70 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
1be80 36 28 29 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  6(). The second 
1be90 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1bea0 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64  database.** hand
1beb0 6c 65 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  le. The third ar
1bec0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
1bed0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
1bee0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
1bef0 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
1bf00 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
1bf10 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
1bf20 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
1bf30 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
1bf40 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
1bf50 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 54 68 65  on required. The
1bf60 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1bf70 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
1bf80 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
1bf90 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
1bfa0 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  nce..**.** The c
1bfb0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1bfc0 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
1bfd0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
1bfe0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
1bff0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
1c000 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
1c010 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1c020 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
1c030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
1c040 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
1c050 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1c060 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
1c070 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
1c080 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
1c090 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
1c0a0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
1c0b0 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
1c0c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1c0d0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
1c0e0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
1c0f0 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
1c100 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
1c110 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
1c120 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
1c130 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
1c140 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
1c150 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
1c160 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
1c170 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
1c180 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
1c190 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
1c1a0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
1c1b0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
1c1c0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
1c1d0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
1c1e0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
1c1f0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
1c200 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
1c210 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1c220 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1c230 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
1c240 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
1c250 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
1c260 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
1c270 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
1c280 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
1c290 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
1c2a0 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
1c2b0 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
1c2c0 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
1c2d0 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
1c2e0 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
1c2f0 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
1c300 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
1c310 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
1c320 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
1c330 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
1c340 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
1c350 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
1c360 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
1c370 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
1c380 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
1c390 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
1c3a0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1c3b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1c3c0 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
1c3d0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
1c3e0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
1c3f0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
1c400 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  new key */.);../
1c410 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1c420 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
1c430 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
1c440 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  me.**.** This fu
1c450 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
1c460 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
1c470 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
1c480 75 74 69 6f 6e 0a 2a 2a 20 61 20 6e 75 6d 62 65  ution.** a numbe
1c490 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
1c4a0 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
1c4b0 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
1c4c0 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
1c4d0 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
1c4e0 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
1c4f0 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
1c500 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64   .** millisecond
1c510 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
1c520 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
1c530 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
1c540 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65  up to .** the ne
1c550 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
1c560 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
1c570 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1c580 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72  p actually .** r
1c590 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
1c5a0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1c5b0 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
1c5c0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
1c5d0 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
1c5e0 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
1c5f0 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
1c600 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
1c610 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1c620 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
1c630 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
1c640 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
1c650 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65 20  CAPI3REF:  Name 
1c660 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
1c670 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
1c680 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 49 66 20 74  Files.**.** If t
1c690 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
1c6a0 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
1c6b0 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
1c6c0 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
1c6d0 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
1c6e0 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74 6f  r (a.ka. directo
1c6f0 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
1c700 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
1c710 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
1c720 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
1c730 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
1c740 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
1c750 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c  riable.** is NUL
1c760 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
1c770 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73 65  SQLite does a se
1c780 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
1c790 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61 72  opriate temporar
1c7a0 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 74  y.** file direct
1c7b0 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
1c7c0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64   not safe to mod
1c7d0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
1c7e0 65 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61 73  e once a databas
1c7f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1c800 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  has been opened.
1c810 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64    It is intended
1c820 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
1c830 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
1c840 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
1c850 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
1c860 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
1c870 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
1c880 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
1c890 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20   have been call 
1c8a0 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  and remain uncha
1c8b0 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e  nged thereafter.
1c8c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
1c8d0 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
1c8e0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
1c8f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c900 20 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66    Test To See If
1c910 20 54 68 65 20 44 61 74 61 62 61 73 65 20 49 73   The Database Is
1c920 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20   In Auto-Commit 
1c930 4d 6f 64 65 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20  Mode.**.** Test 
1c940 74 6f 20 73 65 65 20 77 68 65 74 68 65 72 20 6f  to see whether o
1c950 72 20 6e 6f 74 20 74 68 65 20 64 61 74 61 62 61  r not the databa
1c960 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1c970 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a   in autocommit.*
1c980 2a 20 6d 6f 64 65 2e 20 20 52 65 74 75 72 6e 20  * mode.  Return 
1c990 54 52 55 45 20 69 66 20 69 74 20 69 73 20 61 6e  TRUE if it is an
1c9a0 64 20 46 41 4c 53 45 20 69 66 20 6e 6f 74 2e 20  d FALSE if not. 
1c9b0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
1c9c0 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66   is on.** by def
1c9d0 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69  ault.  Autocommi
1c9e0 74 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  t is disabled by
1c9f0 20 61 20 42 45 47 49 4e 20 73 74 61 74 65 6d 65   a BEGIN stateme
1ca00 6e 74 20 61 6e 64 20 72 65 65 6e 61 62 6c 65 64  nt and reenabled
1ca10 0a 2a 2a 20 62 79 20 74 68 65 20 6e 65 78 74 20  .** by the next 
1ca20 43 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c 42 41  COMMIT or ROLLBA
1ca30 43 4b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  CK..**.** If ano
1ca40 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e  ther thread chan
1ca50 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d  ges the autocomm
1ca60 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65  it status of the
1ca70 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
1ca80 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
1ca90 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
1caa0 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
1cab0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
1cac0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
1cad0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
1cae0 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69  _autocommit(sqli
1caf0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1cb00 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54 68  PI3REF:  Find Th
1cb10 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
1cb20 65 20 41 73 73 6f 63 69 61 74 65 64 20 57 69 74  e Associated Wit
1cb30 68 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  h A Prepared Sta
1cb40 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52 65 74  tement.**.** Ret
1cb50 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  urn the [sqlite3
1cb60 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  *] database hand
1cb70 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a  le to which a.**
1cb80 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
1cb90 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1cba0 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a  ent] belongs..**
1cbb0 20 54 68 69 73 20 69 73 20 74 68 65 20 73 61 6d   This is the sam
1cbc0 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
1cbd0 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74 68  e that was.** th
1cbe0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1cbf0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1cc00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1cc10 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a  r its variants.*
1cc20 2a 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  * that was used 
1cc30 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 73 74  to create the st
1cc40 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
1cc50 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73  irst place..*/.s
1cc60 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
1cc70 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
1cc80 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a  3_stmt*);.../*.*
1cc90 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d  * CAPI3REF: Comm
1cca0 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20  it And Rollback 
1ccb0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
1ccc0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 65  lbacks.**.** The
1ccd0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72  se routines.** r
1cce0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1ccf0 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 62 65   functions to be
1cd00 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
1cd10 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  r a transaction.
1cd20 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 20  ** is committed 
1cd30 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 20  or rolled back. 
1cd40 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   The pArg argume
1cd50 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
1cd60 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ough.** to the c
1cd70 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68 65  allback.  If the
1cd80 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63   callback on a c
1cd90 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74  ommit hook funct
1cda0 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20  ion .** returns 
1cdb0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
1cdc0 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
1cdd0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
1cde0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66  llback..**.** If
1cdf0 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f   another functio
1ce00 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79  n was previously
1ce10 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73   registered, its
1ce20 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72   pArg value is r
1ce30 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65  eturned..** Othe
1ce40 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65  rwise NULL is re
1ce50 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  turned..**.** Re
1ce60 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
1ce70 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
1ce80 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
1ce90 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
1cea0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
1ceb0 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
1cec0 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
1ced0 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c  ve been .** roll
1cee0 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
1cef0 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
1cf00 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
1cf10 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
1cf20 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
1cf30 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
1cf40 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
1cf50 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54 68 65 20  k to occur. The 
1cf60 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
1cf70 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
1cf80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
1cf90 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
1cfa0 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62 65 63  lled.** back bec
1cfb0 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
1cfc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1cfd0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
1cfe0 65 73 65 20 61 72 65 20 65 78 70 65 72 69 6d 65  ese are experime
1cff0 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
1d000 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74 20  and are subject 
1d010 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f  to change..*/.vo
1d020 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  id *sqlite3_comm
1d030 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  it_hook(sqlite3*
1d040 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
1d050 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
1d060 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
1d070 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76  hook(sqlite3*, v
1d080 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20  oid(*)(void *), 
1d090 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1d0a0 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68  API3REF: Data Ch
1d0b0 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f  ange Notificatio
1d0c0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
1d0d0 2a 20 52 65 67 69 73 74 65 72 20 61 20 63 61 6c  * Register a cal
1d0e0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1d0f0 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
1d100 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e   connection iden
1d110 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  tified by the .*
1d120 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  * first argument
1d130 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
1d140 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
1d150 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
1d160 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
1d170 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
1d180 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
1d190 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
1d1a0 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73  nction for the s
1d1b0 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  ame .** database
1d1c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
1d1d0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
1d1e0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1d1f0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
1d200 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
1d210 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
1d220 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70   a .** row is up
1d230 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
1d240 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 68 65 20  or deleted. The 
1d250 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1d260 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1d270 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74  s.** a copy of t
1d280 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1d290 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  t to sqlite3_upd
1d2a0 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68 65 20  ate_hook(). The 
1d2b0 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
1d2c0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
1d2d0 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f 49 4e  one of SQLITE_IN
1d2e0 53 45 52 54 2c 20 53 51 4c 49 54 45 5f 44 45 4c  SERT, SQLITE_DEL
1d2f0 45 54 45 20 6f 72 20 53 51 4c 49 54 45 5f 55 50  ETE or SQLITE_UP
1d300 44 41 54 45 2c 20 64 65 70 65 6e 64 69 6e 67 0a  DATE, depending.
1d310 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ** on the operat
1d320 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
1d330 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20  the callback to 
1d340 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68 65 20  be invoked. The 
1d350 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f  third and .** fo
1d360 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
1d370 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
1d380 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
1d390 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
1d3a0 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61  and .** table na
1d3b0 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
1d3c0 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 20  e affected row. 
1d3d0 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
1d3e0 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
1d3f0 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f 66  .** the rowid of
1d400 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 65   the row. In the
1d410 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61   case of an upda
1d420 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  te, this is the 
1d430 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20  rowid after .** 
1d440 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
1d450 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   place..**.** Th
1d460 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73  e update hook is
1d470 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
1d480 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
1d490 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20  m tables are.** 
1d4a0 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73  modified (i.e. s
1d4b0 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64  qlite_master and
1d4c0 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65   sqlite_sequence
1d4d0 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  )..**.** If anot
1d4e0 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73  her function was
1d4f0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
1d500 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67  stered, its pArg
1d510 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
1d520 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65  ed..** Otherwise
1d530 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
1d540 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  d..*/.void *sqli
1d550 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
1d560 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
1d570 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
1d580 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
1d590 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
1d5a0 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
1d5b0 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
1d5c0 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c  CAPI3REF:  Enabl
1d5d0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
1d5e0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
1d5f0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
1d600 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
1d610 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
1d620 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
1d630 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
1d640 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
1d650 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 63  ctures between c
1d660 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74 68  onnections to th
1d670 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e  e same database.
1d680 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20 65  .** Sharing is e
1d690 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
1d6a0 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20 61  gument is true a
1d6b0 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74  nd disabled if t
1d6c0 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  he argument.** i
1d6d0 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 42  s false..**.** B
1d6e0 65 67 69 6e 6e 69 6e 67 20 69 6e 20 53 51 4c 69  eginning in SQLi
1d6f0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1d700 2c 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20  , cache sharing 
1d710 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
1d720 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61  isabled.** for a
1d730 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
1d740 2e 20 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  .  In prior vers
1d750 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20  ions of SQLite, 
1d760 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65  sharing was.** e
1d770 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
1d780 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
1d790 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
1d7a0 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73  *.** The cache s
1d7b0 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
1d7c0 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
1d7d0 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
1d7e0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
1d7f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
1d800 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1d810 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
1d820 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1d830 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
1d840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d850 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
1d860 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
1d870 64 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 69  de that was.** i
1d880 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
1d890 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
1d8a0 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72  pened..**.** Vir
1d8b0 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e  tual tables cann
1d8c0 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ot be used with 
1d8d0 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20  a shared cache. 
1d8e0 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20   When shared.** 
1d8f0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
1d900 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
1d910 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
1d920 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69  API used to regi
1d930 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20  ster.** virtual 
1d940 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61  tables will alwa
1d950 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
1d960 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  or..**.** This r
1d970 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
1d980 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
1d990 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a  ared cache was.*
1d9a0 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  * enabled or dis
1d9b0 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c  abled successful
1d9c0 6c 79 2e 20 20 41 6e 20 5b 53 51 4c 49 54 45 5f  ly.  An [SQLITE_
1d9d0 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f  ERROR | error co
1d9e0 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  de].** is return
1d9f0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
1da00 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65  .** Shared cache
1da10 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1da20 64 65 66 61 75 6c 74 2e 20 20 42 75 74 20 74 68  default.  But th
1da30 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  is might change 
1da40 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c  in.** future rel
1da50 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
1da60 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
1da70 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73  hat care about s
1da80 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73  hared.** cache s
1da90 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65  etting should se
1daa0 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e  t it explicitly.
1dab0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1dac0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
1dad0 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
1dae0 20 43 41 50 49 33 52 45 46 3a 20 20 41 74 74 65   CAPI3REF:  Atte
1daf0 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
1db00 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 41 74   Memory.**.** At
1db10 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 4e 20  tempt to free N 
1db20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65  bytes of heap me
1db30 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61  mory by dealloca
1db40 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  ting non-essenti
1db50 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  al.** memory all
1db60 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79  ocations held by
1db70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69   the database li
1db80 62 72 61 72 79 20 28 65 78 61 6d 70 6c 65 3a 20  brary (example: 
1db90 6d 65 6d 6f 72 79 20 0a 2a 2a 20 75 73 65 64 20  memory .** used 
1dba0 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
1dbb0 65 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f  e pages to impro
1dbc0 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 29 2e  ve performance).
1dbd0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1dbe0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
1dbf0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1dc00 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20  3REF:  Impose A 
1dc10 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
1dc20 7a 65 0a 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20 61  ze.**.** Place a
1dc30 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e   "soft" limit on
1dc40 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
1dc50 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
1dc60 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
1dc70 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 20  .** by SQLite.  
1dc80 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
1dc90 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
1dca0 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20  uested .** that 
1dcb0 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
1dcc0 20 73 70 65 63 69 66 69 65 64 20 6c 69 6d 69 74   specified limit
1dcd0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  , [sqlite3_relea
1dce0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a  se_memory()] is.
1dcf0 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f  ** invoked one o
1dd00 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
1dd10 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61  free up some spa
1dd20 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c  ce before the al
1dd30 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d  location.** is m
1dd40 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  ade..**.** The l
1dd50 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
1dd60 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69  soft", because i
1dd70 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  f [sqlite3_relea
1dd80 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e  se_memory()] can
1dd90 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66 66  not.** free suff
1dda0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f  icient memory to
1ddb0 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d   prevent the lim
1ddc0 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78  it from being ex
1ddd0 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d  ceeded,.** the m
1dde0 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
1ddf0 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68  ed anyway and th
1de00 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  e current operat
1de10 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a  ion proceeds..**
1de20 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f  .** A negative o
1de30 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
1de40 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
1de50 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
1de60 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
1de70 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
1de80 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
1de90 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
1dea0 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
1deb0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65  xhausted..** The
1dec0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
1ded0 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
1dee0 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
1def0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
1df00 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
1df10 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
1df20 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20  ft heap limit.  
1df30 42 75 74 20 69 66 20 69 74 0a 2a 2a 20 69 73 20  But if it.** is 
1df40 75 6e 61 62 6c 65 20 74 6f 20 72 65 64 75 63 65  unable to reduce
1df50 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62 65   memory usage be
1df60 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 6c 69 6d  low the soft lim
1df70 69 74 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69  it, execution wi
1df80 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77  ll.** continue w
1df90 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20  ithout error or 
1dfa0 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54  notification.  T
1dfb0 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c  his is why the l
1dfc0 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c  imit is .** call
1dfd0 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  ed a "soft" limi
1dfe0 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f  t.  It is adviso
1dff0 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  ry only..**.** T
1e000 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
1e010 69 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  it is implemente
1e020 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
1e030 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
1e040 6d 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  m()].** interfac
1e050 65 2e 20 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  e.  Only a singl
1e060 65 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20 69  e memory alarm i
1e070 73 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  s available in t
1e080 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 69 6d  he default.** im
1e090 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1e0a0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
1e0b0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
1e0c0 6e 20 61 6c 73 6f 20 75 73 65 73 20 74 68 65 0a  n also uses the.
1e0d0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20  ** memory alarm 
1e0e0 69 6e 74 65 72 66 61 63 65 20 69 74 20 77 69 6c  interface it wil
1e0f0 6c 20 69 6e 74 65 72 66 65 72 65 20 77 69 74 68  l interfere with
1e100 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
1e110 66 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65  f the.** soft he
1e120 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 75 6e 64  ap limit and und
1e130 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 20  efined behavior 
1e140 77 69 6c 6c 20 72 65 73 75 6c 74 2e 20 20 0a 2a  will result.  .*
1e150 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1e160 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1e170 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .0, this routine
1e180 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65   only constraine
1e190 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  d the memory.** 
1e1a0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73  allocated by a s
1e1b0 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74  ingle thread - t
1e1c0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
1e1d0 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75  n which this rou
1e1e0 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42  tine.** runs.  B
1e1f0 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51  eginning with SQ
1e200 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1e210 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61  .0, the soft hea
1e220 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70  p limit is.** ap
1e230 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72  plied to all thr
1e240 65 61 64 73 2e 20 20 54 68 65 20 76 61 6c 75 65  eads.  The value
1e250 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74   specified for t
1e260 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
1e270 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65  it.** is an uppe
1e280 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74  r bound on the t
1e290 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  otal memory allo
1e2a0 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74  cation for all t
1e2b0 68 72 65 61 64 73 2e 20 20 49 6e 0a 2a 2a 20 76  hreads.  In.** v
1e2c0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65  ersion 3.5.0 the
1e2d0 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69  re is no mechani
1e2e0 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20  sm for limiting 
1e2f0 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20 66  the heap usage f
1e300 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c  or.** individual
1e310 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69   threads..*/.voi
1e320 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  d sqlite3_soft_h
1e330 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a  eap_limit(int);.
1e340 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e350 20 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61    Extract Metada
1e360 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
1e370 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a  n Of A Table.**.
1e380 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a  ** This routine.
1e390 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d  ** returns meta-
1e3a0 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65  data about a spe
1e3b0 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20  cific column of 
1e3c0 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62  a specific datab
1e3d0 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63  ase.** table acc
1e3e0 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68  essible using th
1e3f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  e connection han
1e400 64 6c 65 20 70 61 73 73 65 64 20 61 73 20 74 68  dle passed as th
1e410 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
1e420 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   .** argument..*
1e430 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20  *.** The column 
1e440 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
1e450 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69   the second, thi
1e460 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
1e470 72 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20  rameters to .** 
1e480 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54  this function. T
1e490 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1e4a0 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68  ter is either th
1e4b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1e4c0 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20  tabase.** (i.e. 
1e4d0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f  "main", "temp" o
1e4e0 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
1e4f0 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
1e500 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
1e510 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
1e520 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  L. If it is NULL
1e530 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
1e540 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
1e550 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
1e560 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
1e570 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
1e580 69 74 68 6d 20 61 73 20 74 68 65 20 64 61 74 61  ithm as the data
1e590 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73  base engine uses
1e5a0 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20   to .** resolve 
1e5b0 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
1e5c0 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
1e5d0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e  .** The third an
1e5e0 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
1e5f0 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
1e600 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
1e610 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a  le and column .*
1e620 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
1e630 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
1e640 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
1e650 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
1e660 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20  ameters .** may 
1e670 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d  be NULL..**.** M
1e680 65 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  eta information 
1e690 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77  is returned by w
1e6a0 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65  riting to the me
1e6b0 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70  mory locations p
1e6c0 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20  assed as.** the 
1e6d0 35 74 68 20 61 6e 64 20 73 75 62 73 65 71 75 65  5th and subseque
1e6e0 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  nt parameters to
1e6f0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
1e700 41 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a  Any of these .**
1e710 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62   arguments may b
1e720 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68  e NULL, in which
1e730 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73   case the corres
1e740 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20  ponding element 
1e750 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f  of meta .** info
1e760 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74  rmation is ommit
1e770 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ted..**.** <pre>
1e780 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20  .** Parameter   
1e790 20 20 4f 75 74 70 75 74 20 54 79 70 65 20 20 20    Output Type   
1e7a0 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a     Description.*
1e7b0 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  * --------------
1e7c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1e7d0 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74  -----.**.**   5t
1e7e0 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20  h         const 
1e7f0 63 68 61 72 2a 20 20 20 20 20 20 44 61 74 61 20  char*      Data 
1e800 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20  type.**   6th   
1e810 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72        const char
1e820 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74  *      Name of t
1e830 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  he default colla
1e840 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a  tion sequence .*
1e850 2a 20 20 20 37 74 68 20 20 20 20 20 20 20 20 20  *   7th         
1e860 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20  int             
1e870 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c   True if the col
1e880 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55  umn has a NOT NU
1e890 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  LL constraint.**
1e8a0 20 20 20 38 74 68 20 20 20 20 20 20 20 20 20 69     8th         i
1e8b0 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
1e8c0 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
1e8d0 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  mn is part of th
1e8e0 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a  e PRIMARY KEY.**
1e8f0 20 20 20 39 74 68 20 20 20 20 20 20 20 20 20 69     9th         i
1e900 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
1e910 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
1e920 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d  mn is AUTOINCREM
1e930 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a  ENT.** </pre>.**
1e940 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
1e950 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  y pointed to by 
1e960 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f  the character po
1e970 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
1e980 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c  for the .** decl
1e990 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64  aration type and
1e9a0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
1e9b0 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c  nce is valid onl
1e9c0 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  y until the next
1e9d0 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79   .** call to any
1e9e0 20 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63   sqlite API func
1e9f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tion..**.** If t
1ea00 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62  he specified tab
1ea10 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61  le is actually a
1ea20 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65   view, then an e
1ea30 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1ea40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
1ea50 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
1ea60 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
1ea70 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
1ea80 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45  nd an .** INTEGE
1ea90 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f  R PRIMARY KEY co
1eaa0 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78  lumn has been ex
1eab0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
1eac0 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  d, then the outp
1ead0 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ut .** parameter
1eae0 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
1eaf0 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
1eb00 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66  lared column. If
1eb10 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20   there is no.** 
1eb20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
1eb30 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20  red IPK column, 
1eb40 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20  then the output 
1eb50 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
1eb60 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  et as .** follow
1eb70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  s:.**.** <pre>.*
1eb80 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a  *     data type:
1eb90 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20   "INTEGER".**   
1eba0 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75    collation sequ
1ebb0 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a  ence: "BINARY".*
1ebc0 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20  *     not null: 
1ebd0 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79  0.**     primary
1ebe0 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61   key: 1.**     a
1ebf0 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30  uto increment: 0
1ec00 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
1ec10 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   This function m
1ec20 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
1ec30 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
1ec40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
1ec50 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
1ec60 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
1ec70 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
1ec80 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
1ec90 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
1eca0 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
1ecb0 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72  nd, an SQLITE er
1ecc0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
1ecd0 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f  rned and an erro
1ece0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66  r message.** lef
1ecf0 74 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  t in the databas
1ed00 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20  e handle (to be 
1ed10 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20  retrieved using 
1ed20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1ed30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  )..**.** This AP
1ed40 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
1ed50 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
1ed60 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
1ed70 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
1ed80 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
1ed90 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f  _METADATA prepro
1eda0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
1edb0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
1edc0 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75  lite3_table_colu
1edd0 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73  mn_metadata(.  s
1ede0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1edf0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
1ee00 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20  nnection handle 
1ee10 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1ee20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
1ee30 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d   /* Database nam
1ee40 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63  e or NULL */.  c
1ee50 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
1ee60 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61  eName,     /* Ta
1ee70 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f  ble name */.  co
1ee80 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
1ee90 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c  nName,    /* Col
1eea0 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68  umn name */.  ch
1eeb0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74  ar const **pzDat
1eec0 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54  aType,    /* OUT
1eed0 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61  PUT: Declared da
1eee0 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61  ta type */.  cha
1eef0 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c  r const **pzColl
1ef00 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50  Seq,     /* OUTP
1ef10 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65  UT: Collation se
1ef20 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20  quence name */. 
1ef30 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20   int *pNotNull, 
1ef40 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1ef50 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
1ef60 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
1ef70 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20  int exists */.  
1ef80 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79  int *pPrimaryKey
1ef90 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  ,           /* O
1efa0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
1efb0 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b  olumn part of PK
1efc0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f   */.  int *pAuto
1efd0 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20  inc             
1efe0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
1eff0 65 20 69 66 20 63 6f 6c 75 6d 73 20 69 73 20 61  e if colums is a
1f000 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f  uto-increment */
1f010 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1f020 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74  REF: Load An Ext
1f030 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74  ension.**.** Att
1f040 65 6d 70 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20  empt to load an 
1f050 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
1f060 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
1f070 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a  ed in the file.*
1f080 2a 20 7a 46 69 6c 65 2e 20 20 54 68 65 20 65 6e  * zFile.  The en
1f090 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
1f0a0 6f 63 2e 20 20 7a 50 72 6f 63 20 6d 61 79 20 62  oc.  zProc may b
1f0b0 65 20 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  e 0 in which cas
1f0c0 65 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66  e the.** name of
1f0d0 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
1f0e0 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71   defaults to "sq
1f0f0 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f  lite3_extension_
1f100 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74  init"..**.** Ret
1f110 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1f120 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b  on success and [
1f130 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
1f140 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20   something goes 
1f150 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  wrong..**.** If 
1f160 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
1f170 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20  and pzErrMsg is 
1f180 6e 6f 74 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c  not 0, then fill
1f190 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20   *pzErrMsg with 
1f1a0 0a 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67  .** error messag
1f1b0 65 20 74 65 78 74 2e 20 20 54 68 65 20 63 61 6c  e text.  The cal
1f1c0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
1f1d0 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d  ould free this m
1f1e0 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c  emory.** by call
1f1f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1f200 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65  e()]..**.** Exte
1f210 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75  nsion loading mu
1f220 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73  st be enabled us
1f230 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
1f240 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
1f250 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74  on()].** prior t
1f260 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41  o calling this A
1f270 50 49 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77  PI or an error w
1f280 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
1f290 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f2a0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
1f2b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1f2c0 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
1f2d0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
1f2e0 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
1f2f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
1f300 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
1f310 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
1f320 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
1f330 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
1f340 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
1f350 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
1f360 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
1f370 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
1f380 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
1f390 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
1f3a0 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
1f3b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
1f3c0 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
1f3d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f3e0 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  F:  Enable Or Di
1f3f0 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20  sable Extension 
1f400 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f  Loading.**.** So
1f410 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
1f420 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
1f430 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
1f440 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
1f450 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
1f460 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
1f470 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
1f480 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
1f490 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
1f4a0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
1f4b0 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
1f4c0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
1f4d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  the following.**
1f4e0 20 41 50 49 20 69 73 20 70 72 6f 76 69 64 65 64   API is provided
1f4f0 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
1f500 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
1f510 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
1f520 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e  m on and.** off.
1f530 20 20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64    It is off by d
1f540 65 66 61 75 6c 74 2e 20 20 53 65 65 20 74 69 63  efault.  See tic
1f550 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a  ket #1863..**.**
1f560 20 43 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   Call this routi
1f570 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31  ne with onoff==1
1f580 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
1f590 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a  on loading on.**
1f5a0 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74   and call it wit
1f5b0 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75  h onoff==0 to tu
1f5c0 72 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61  rn it back off a
1f5d0 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gain..*/.int sql
1f5e0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
1f5f0 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74  _extension(sqlit
1f600 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66  e3 *db, int onof
1f610 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
1f620 52 45 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67  REF: Make Arrang
1f630 65 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61  ements To Automa
1f640 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20  tically Load An 
1f650 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  Extension.**.** 
1f660 52 65 67 69 73 74 65 72 20 61 6e 20 65 78 74 65  Register an exte
1f670 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e  nsion entry poin
1f680 74 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61  t that is automa
1f690 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a  tically invoked.
1f6a0 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ** whenever a ne
1f6b0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1f6c0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20  ction is opened 
1f6d0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1f6e0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1f6f0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
1f700 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
1f710 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  v2()]..**.** Thi
1f720 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76  s API can be inv
1f730 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20  oked at program 
1f740 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72  startup in order
1f750 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
1f760 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74  one or more stat
1f770 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78  ically linked ex
1f780 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69  tensions that wi
1f790 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a  ll be available.
1f7a0 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61  ** to all new da
1f7b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f7c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 44 75 70 6c 69 63  ns..**.** Duplic
1f7d0 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  ate extensions a
1f7e0 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63  re detected so c
1f7f0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1f800 69 6e 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ine multiple.** 
1f810 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
1f820 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73  ame extension is
1f830 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a   harmless..**.**
1f840 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   This routine st
1f850 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ores a pointer t
1f860 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  o the extension 
1f870 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74  in an array.** t
1f880 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20  hat is obtained 
1f890 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2e 20 20  from malloc().  
1f8a0 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d  If you run a mem
1f8b0 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63  ory leak.** chec
1f8c0 6b 65 72 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67  ker on your prog
1f8d0 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72  ram and it repor
1f8e0 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73  ts a leak becaus
1f8f0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 61 72 72  e of this.** arr
1f900 61 79 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  ay, then invoke 
1f910 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d 61 74  [sqlite3_automat
1f920 69 63 5f 65 78 74 65 6e 73 69 6f 6e 5f 72 65 73  ic_extension_res
1f930 65 74 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74  et()] prior.** t
1f940 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72  o shutdown to fr
1f950 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a  ee the memory..*
1f960 2a 0a 2a 2a 20 41 75 74 6f 6d 61 74 69 63 20 65  *.** Automatic e
1f970 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
1f980 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
1f990 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ds..**.** This i
1f9a0 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
1f9b0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
1f9c0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1f9d0 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20  e or.** removal 
1f9e0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
1f9f0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
1fa00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74  .int sqlite3_aut
1fa10 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64  o_extension(void
1fa20 20 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a   *xEntryPoint);.
1fa30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fa40 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69  : Reset Automati
1fa50 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  c Extension Load
1fa60 69 6e 67 0a 2a 2a 0a 2a 2a 20 44 69 73 61 62 6c  ing.**.** Disabl
1fa70 65 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79  e all previously
1fa80 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f   registered auto
1fa90 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
1faa0 2e 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69  .  This.** routi
1fab0 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
1fac0 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
1fad0 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d  r [sqlite3_autom
1fae0 61 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e 28 29  atic_extension()
1faf0 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  ].** calls..**.*
1fb00 2a 20 54 68 69 73 20 63 61 6c 6c 20 64 69 73 61  * This call disa
1fb10 62 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65  bled automatic e
1fb20 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c  xtensions in all
1fb30 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20   threads..**.** 
1fb40 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  This interface i
1fb50 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
1fb60 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
1fb70 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65   change or.** re
1fb80 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
1fb90 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
1fba0 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  te..*/.void sqli
1fbb0 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
1fbc0 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  xtension(void);.
1fbd0 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45  ../*.****** EXPE
1fbe0 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65  RIMENTAL - subje
1fbf0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74  ct to change wit
1fc00 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a  hout notice ****
1fc10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a  **********.**.**
1fc20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
1fc30 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
1fc40 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73  ble mechanism is
1fc50 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
1fc60 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
1fc70 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
1fc80 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
1fc90 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
1fca0 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
1fcb0 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
1fcc0 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
1fcd0 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
1fce0 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
1fcf0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
1fd00 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
1fd10 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
1fd20 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  ablizes, we will
1fd30 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
1fd40 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
1fd50 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
1fd60 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
1fd70 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
1fd80 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72  t..*/../*.** Str
1fd90 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20  uctures used by 
1fda0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
1fdb0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74  e interface.*/.t
1fdc0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1fdd0 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74  lite3_vtab sqlit
1fde0 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66  e3_vtab;.typedef
1fdf0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1fe00 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74  index_info sqlit
1fe10 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74  e3_index_info;.t
1fe20 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1fe30 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
1fe40 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  r sqlite3_vtab_c
1fe50 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73  ursor;.typedef s
1fe60 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
1fe70 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64  dule sqlite3_mod
1fe80 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 6d 6f  ule;../*.** A mo
1fe90 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73 20  dule is a class 
1fea0 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  of virtual table
1feb0 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  s.  Each module 
1fec0 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79  is defined.** by
1fed0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
1fee0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
1fef0 72 75 63 74 75 72 65 2e 20 20 54 68 69 73 20 73  ructure.  This s
1ff00 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74  tructure consist
1ff10 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  s.** mostly of m
1ff20 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
1ff30 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74  odule..*/.struct
1ff40 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
1ff50 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
1ff60 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  ;.  int (*xCreat
1ff70 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  e)(sqlite3*, voi
1ff80 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
1ff90 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
1ffa0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
1ffb0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
1ffc0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
1ffd0 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
1ffe0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
1fff0 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  *xConnect)(sqlit
20000 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
20010 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
20020 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
20030 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
20040 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
20050 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
20060 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
20070 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e  .  int (*xBestIn
20080 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61  dex)(sqlite3_vta
20090 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
200a0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a  3_index_info*);.
200b0 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e    int (*xDisconn
200c0 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ect)(sqlite3_vta
200d0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
200e0 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c   (*xDestroy)(sql
200f0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
20100 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  );.  int (*xOpen
20110 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
20120 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76  pVTab, sqlite3_v
20130 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43  tab_cursor **ppC
20140 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ursor);.  int (*
20150 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
20160 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
20170 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
20180 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
20190 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
201a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
201b0 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
201c0 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
201d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
201e0 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78  argv);.  int (*x
201f0 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74  Next)(sqlite3_vt
20200 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
20210 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74  nt (*xEof)(sqlit
20220 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
20230 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d  ;.  int (*xColum
20240 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  n)(sqlite3_vtab_
20250 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
20260 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
20270 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  .  int (*xRowid)
20280 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
20290 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  rsor*, sqlite3_i
202a0 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20  nt64 *pRowid);. 
202b0 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28   int (*xUpdate)(
202c0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20  sqlite3_vtab *, 
202d0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  int, sqlite3_val
202e0 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69  ue **, sqlite3_i
202f0 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28  nt64 *);.  int (
20300 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33  *xBegin)(sqlite3
20310 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
20320 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
20330 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
20340 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d  b);.  int (*xCom
20350 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
20360 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
20370 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71   (*xRollback)(sq
20380 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
20390 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  b);.  int (*xFin
203a0 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74  dFunction)(sqlit
203b0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
203c0 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20  int nArg, const 
203d0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20  char *zName,.   
203e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
203f0 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75      void (**pxFu
20400 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
20410 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
20420 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20  _value**),.     
20430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20440 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b    void **ppArg);
20450 0a 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d  ..  int (*xRenam
20460 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
20470 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68  *pVtab, const ch
20480 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f  ar *zNew);.};../
20490 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
204a0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
204b0 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
204c0 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
204d0 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69  sed to.** pass i
204e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20  nformation into 
204f0 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20  and receive the 
20500 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78  reply from the x
20510 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74  BestIndex.** met
20520 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  hod of an sqlite
20530 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66  3_module.  The f
20540 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e  ields under **In
20550 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a  puts** are the.*
20560 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73  * inputs to xBes
20570 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72  tIndex and are r
20580 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74  ead-only.  xBest
20590 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74  Index inserts it
205a0 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  s.** results int
205b0 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a  o the **Outputs*
205c0 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20  * fields..**.** 
205d0 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
205e0 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20  ] array records 
205f0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
20600 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 0a  straints of the.
20610 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20  ** form:.**.**  
20620 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50         column OP
20630 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72   expr.**.** Wher
20640 65 20 4f 50 20 69 73 20 3d 2c 20 3c 2c 20 3c 3d  e OP is =, <, <=
20650 2c 20 3e 2c 20 6f 72 20 3e 3d 2e 20 20 54 68 65  , >, or >=.  The
20660 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
20670 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a 2a  ator is stored.*
20680 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  * in aConstraint
20690 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65  [].op.  The inde
206a0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
206b0 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a  is stored in .**
206c0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
206d0 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72  Column.  aConstr
206e0 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
206f0 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
20700 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
20710 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
20720 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
20730 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
20740 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
20750 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
20760 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a   it cannot..**.*
20770 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20  * The optimizer 
20780 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
20790 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74  verts terms of t
207a0 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50  he form "expr OP
207b0 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20   column".** and 
207c0 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70  makes other simp
207d0 6c 69 66 69 63 61 74 69 6e 6f 73 20 74 6f 20 74  lificatinos to t
207e0 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
207f0 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
20800 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20  .** get as many 
20810 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
20820 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d  ms into the form
20830 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20   shown above as 
20840 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  possible..** The
20850 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
20860 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74  rray only report
20870 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  s WHERE clause t
20880 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72  erms in the corr
20890 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74  ect.** form that
208a0 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61   refer to the pa
208b0 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c  rticular virtual
208c0 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65   table being que
208d0 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f  ried..**.** Info
208e0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
208f0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
20900 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  e is stored in a
20910 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61  OrderBy[]..** Ea
20920 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65  ch term of aOrde
20930 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f  rBy records a co
20940 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45  lumn of the ORDE
20950 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a  R BY clause..**.
20960 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 65  ** The xBestInde
20970 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69  x method must fi
20980 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  ll aConstraintUs
20990 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72  age[] with infor
209a0 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
209b0 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20  what parameters 
209c0 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74  to pass to xFilt
209d0 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65  er.  If argvInde
209e0 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  x>0 then.** the 
209f0 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
20a00 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
20a10 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74  ding aConstraint
20a20 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a  [] is evaluated.
20a30 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74  ** and becomes t
20a40 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20  he argvIndex-th 
20a50 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20  entry in argv.  
20a60 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
20a70 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
20a80 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
20a90 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
20aa0 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
20ab0 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
20ac0 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
20ad0 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
20ae0 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
20af0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
20b00 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74  idxNum and idxPt
20b10 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63  r values are rec
20b20 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64  orded and passed
20b30 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a   into xFilter..*
20b40 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  * sqlite3_free()
20b50 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65   is used to free
20b60 20 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 54   idxPtr if needT
20b70 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74  oFreeIdxPtr is t
20b80 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  rue..**.** The o
20b90 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d  rderByConsumed m
20ba0 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74  eans that output
20bb0 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69   from xFilter wi
20bc0 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
20bd0 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
20be0 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
20bf0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
20c00 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
20c10 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
20c20 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
20c30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d  .**.** The estim
20c40 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69  atedCost value i
20c50 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  s an estimate of
20c60 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69   the cost of doi
20c70 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63  ng the.** partic
20c80 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20  ular lookup.  A 
20c90 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74  full scan of a t
20ca0 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72  able with N entr
20cb0 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a  ies should have.
20cc0 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20  ** a cost of N. 
20cd0 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68   A binary search
20ce0 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e   of a table of N
20cf0 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
20d00 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f  have a.** cost o
20d10 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  f approximately 
20d20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63  log(N)..*/.struc
20d30 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
20d40 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75  info {.  /* Inpu
20d50 74 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e  ts */.  const in
20d60 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20  t nConstraint;  
20d70 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
20d80 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73  entries in aCons
20d90 74 72 61 69 6e 74 20 2a 2f 0a 20 20 63 6f 6e 73  traint */.  cons
20da0 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
20db0 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e  _index_constrain
20dc0 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  t {.     int iCo
20dd0 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
20de0 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20     /* Column on 
20df0 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
20e00 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  f constraint */.
20e10 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
20e20 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f  ar op;         /
20e30 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65  * Constraint ope
20e40 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e  rator */.     un
20e50 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62  signed char usab
20e60 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20  le;     /* True 
20e70 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  if this constrai
20e80 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a  nt is usable */.
20e90 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66       int iTermOf
20ea0 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f  fset;          /
20eb0 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  * Used internall
20ec0 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73  y - xBestIndex s
20ed0 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a  hould ignore */.
20ee0 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e 73    } *const aCons
20ef0 74 72 61 69 6e 74 3b 20 20 20 20 20 20 2f 2a 20  traint;      /* 
20f00 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63  Table of WHERE c
20f10 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
20f20 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74  s */.  const int
20f30 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20   nOrderBy;      
20f40 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74    /* Number of t
20f50 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45  erms in the ORDE
20f60 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20  R BY clause */. 
20f70 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
20f80 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65  lite3_index_orde
20f90 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  rby {.     int i
20fa0 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
20fb0 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e       /* Column n
20fc0 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e  umber */.     un
20fd0 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63  signed char desc
20fe0 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20  ;       /* True 
20ff0 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65  for DESC.  False
21000 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d   for ASC. */.  }
21010 20 2a 63 6f 6e 73 74 20 61 4f 72 64 65 72 42 79   *const aOrderBy
21020 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65  ;         /* The
21030 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
21040 20 2a 2f 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74   */..  /* Output
21050 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  s */.  struct sq
21060 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73  lite3_index_cons
21070 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20  traint_usage {. 
21080 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78     int argvIndex
21090 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69  ;           /* i
210a0 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74  f >0, constraint
210b0 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76   is part of argv
210c0 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20   to xFilter */. 
210d0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
210e0 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44   omit;      /* D
210f0 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73  o not code a tes
21100 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74  t for this const
21110 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 63 6f  raint */.  } *co
21120 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  nst aConstraintU
21130 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e  sage;.  int idxN
21140 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  um;             
21150 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65     /* Number use
21160 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68  d to identify th
21170 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61  e index */.  cha
21180 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
21190 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
211a0 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
211b0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
211c0 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e  3_malloc */.  in
211d0 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53  t needToFreeIdxS
211e0 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65  tr;      /* Free
211f0 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71   idxStr using sq
21200 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20  lite3_free() if 
21210 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72  true */.  int or
21220 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20  derByConsumed;  
21230 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
21240 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64  output is alread
21250 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64  y ordered */.  d
21260 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43  ouble estimatedC
21270 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74  ost;      /* Est
21280 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75  imated cost of u
21290 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20  sing this index 
212a0 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51  */.};.#define SQ
212b0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
212c0 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64  RAINT_EQ    2.#d
212d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
212e0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54  EX_CONSTRAINT_GT
212f0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
21300 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
21310 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64  RAINT_LE    8.#d
21320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
21330 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54  EX_CONSTRAINT_LT
21340 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
21350 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
21360 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a  TRAINT_GE    32.
21370 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
21380 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
21390 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20  MATCH 64../*.** 
213a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
213b0 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
213c0 20 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61   a new module na
213d0 6d 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74  me with an SQLit
213e0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
213f0 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d    Module names m
21400 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
21410 64 20 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e  d before creatin
21420 67 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c  g new.** virtual
21430 20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d   tables on the m
21440 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65  odule, or before
21450 20 75 73 69 6e 67 20 70 72 65 65 78 69 73 74 69   using preexisti
21460 6e 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  ng virtual.** ta
21470 62 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  bles of the modu
21480 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  le..*/.int sqlit
21490 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
214a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
214b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
214c0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
214d0 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
214e0 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
214f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
21500 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
21510 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
21520 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
21530 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20  ite3_module *,  
21540 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
21550 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
21560 20 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20   void *         
21570 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
21580 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
21590 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
215a0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69  */.);../*.** Thi
215b0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65  s routine is ide
215c0 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71  ntical to the sq
215d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
215e0 75 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f  ule() method abo
215f0 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ve,.** except th
21600 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64  at it allows a d
21610 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
21620 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69  on to be specifi
21630 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65  ed. It is.** eve
21640 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e  n more experimen
21650 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73  tal than the res
21660 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  t of the virtual
21670 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a   tables API..*/.
21680 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
21690 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20  te_module_v2(.  
216a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
216b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
216c0 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
216d0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
216e0 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
216f0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
21700 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
21710 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
21720 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
21730 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a  _module *,    /*
21740 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
21750 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
21760 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
21770 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
21780 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
21790 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20  te/xConnect */. 
217a0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
217b0 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d  (void*)     /* M
217c0 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72  odule destructor
217d0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a   function */.);.
217e0 0a 2f 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64  ./*.** Every mod
217f0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
21800 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
21810 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ss of the follow
21820 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ing structure.**
21830 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70   to describe a p
21840 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
21850 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ce of the module
21860 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73  .  Each subclass
21870 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 79 6c   will.** be tayl
21880 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63  ored to the spec
21890 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68  ific needs of th
218a0 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  e module impleme
218b0 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a  ntation.   The.*
218c0 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69  * purpose of thi
218d0 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20  s superclass is 
218e0 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69  to define certai
218f0 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72  n fields that ar
21900 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61  e common.** to a
21910 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ll module implem
21920 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  entations..**.**
21930 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
21940 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20  methods can set 
21950 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
21960 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a   by assigning a.
21970 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  ** string obtain
21980 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
21990 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72  mprintf() to zEr
219a0 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f  rMsg.  The metho
219b0 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65  d should.** take
219c0 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70   care that any p
219d0 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66  rior string is f
219e0 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  reed by a call t
219f0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
21a00 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73  .** prior to ass
21a10 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72  igning a new str
21a20 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ing to zErrMsg. 
21a30 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   After the error
21a40 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
21a50 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
21a60 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
21a70 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
21a80 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
21a90 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
21aa0 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
21ab0 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
21ac0 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
21ad0 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a   zeroed.  Note.*
21ae0 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d  * that sqlite3_m
21af0 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
21b00 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20  ite3_free() are 
21b10 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72  used on the zErr
21b20 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e  Msg field.** sin
21b30 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ce virtual table
21b40 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69  s are commonly i
21b50 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f  mplemented in lo
21b60 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
21b70 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f  s which.** do no
21b80 74 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f  t have access to
21b90 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28   sqlite3MPrintf(
21ba0 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65  ) or sqlite3Free
21bb0 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ()..*/.struct sq
21bc0 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
21bd0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
21be0 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
21bf0 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
21c00 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
21c10 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
21c20 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
21c30 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
21c40 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20   internally */. 
21c50 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
21c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21c70 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
21c80 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
21c90 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
21ca0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
21cb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
21cc0 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
21cd0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
21ce0 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76  lds */.};../* Ev
21cf0 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ery module imple
21d00 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
21d10 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
21d20 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
21d30 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72  ture.** to descr
21d40 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74  ibe cursors that
21d50 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20   point into the 
21d60 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e  virtual table an
21d70 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
21d80 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
21d90 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
21da0 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
21db0 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
21dc0 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  ** xOpen method 
21dd0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
21de0 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  Each module impl
21df0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
21e00 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f  define.** the co
21e10 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f  ntent of a curso
21e20 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73  r structure to s
21e30 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64  uit its own need
21e40 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75  s..**.** This su
21e50 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20  perclass exists 
21e60 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69  in order to defi
21e70 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65  ne fields of the
21e80 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20   cursor that.** 
21e90 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  are common to al
21ea0 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  l implementation
21eb0 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  s..*/.struct sql
21ec0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
21ed0 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61   {.  sqlite3_vta
21ee0 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f  b *pVtab;      /
21ef0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
21f00 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a  of this cursor *
21f10 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
21f20 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
21f30 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
21f40 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
21f50 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
21f60 0a 2f 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61  ./*.** The xCrea
21f70 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20  te and xConnect 
21f80 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64  methods of a mod
21f90 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c  ule use the foll
21fa0 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20  owing API.** to 
21fb0 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d  declare the form
21fc0 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e  at (the names an
21fd0 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74  d datatypes of t
21fe0 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a  he columns) of.*
21ff0 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  * the virtual ta
22000 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d  bles they implem
22010 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
22020 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
22030 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
22040 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61   char *zCreateTa
22050 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72  ble);../*.** Vir
22060 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20  tual tables can 
22070 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74  provide alternat
22080 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
22090 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ons of functions
220a0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46  .** using the xF
220b0 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68  indFunction meth
220c0 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20  od.  But global 
220d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73  versions of thos
220e0 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d  e functions.** m
220f0 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64  ust exist in ord
22100 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61  er to be overloa
22110 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ded..**.** This 
22120 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61  API makes sure a
22130 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20   global version 
22140 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  of a function wi
22150 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
22160 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62  ** name and numb
22170 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
22180 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20   exists.  If no 
22190 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78  such function ex
221a0 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ists.** before t
221b0 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65  his API is calle
221c0 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f  d, a new functio
221d0 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  n is created.  T
221e0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
221f0 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20  n.** of the new 
22200 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20  function always 
22210 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74  causes an except
22220 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e  ion to be thrown
22230 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77  .  So.** the new
22240 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
22250 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69   good for anythi
22260 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49  ng by itself.  I
22270 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f  ts only.** purpo
22280 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c  se is to be a pl
22290 61 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74  ace-holder funct
222a0 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20  ion that can be 
222b0 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79  overloaded.** by
222c0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e   virtual tables.
222d0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
222e0 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64  should be consid
222f0 65 72 65 64 20 70 61 72 74 20 6f 66 20 74 68 65  ered part of the
22300 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
22310 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69  nterface,.** whi
22320 63 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ch is experiment
22330 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74  al and subject t
22340 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  o change..*/.int
22350 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61   sqlite3_overloa
22360 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74  d_function(sqlit
22370 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
22380 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20  *zFuncName, int 
22390 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  nArg);../*.** Th
223a0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
223b0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
223c0 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e   mechanism defin
223d0 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75  ed above (back u
223e0 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e  p.** to a commen
223f0 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d  t remarkably sim
22400 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65  ilar to this one
22410 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  ) is currently c
22420 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
22430 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
22440 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
22450 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
22460 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
22470 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
22480 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
22490 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
224a0 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
224b0 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
224c0 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
224d0 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
224e0 6d 20 73 74 61 62 6c 69 7a 65 73 2c 20 77 65 20  m stablizes, we 
224f0 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
22500 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
22510 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
22520 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
22530 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
22540 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a  mment..**.******
22550 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20   EXPERIMENTAL - 
22560 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
22570 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
22580 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a   **************.
22590 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
225a0 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20  EF: A Handle To 
225b0 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a  An Open BLOB.**.
225c0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
225d0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
225e0 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
225f0 20 69 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a 20   is used to .** 
22600 72 65 70 72 65 73 65 6e 74 20 61 6e 20 62 6c 6f  represent an blo
22610 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62 6c 6f  b-handle.  A blo
22620 62 2d 68 61 6e 64 6c 65 20 69 73 20 63 72 65 61  b-handle is crea
22630 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ted by.** [sqlit
22640 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
22650 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79  and destroyed by
22660 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
22670 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lose()]..** The 
22680 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
22690 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
226a0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
226b0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63   interfaces.** c
226c0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
226d0 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c  ad or write smal
226e0 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66  l subsections of
226f0 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68   the blob..** Th
22700 65 20 5b 73 71 6c 74 69 65 33 5f 62 6c 6f 62 5f  e [sqltie3_blob_
22710 73 69 7a 65 28 29 5d 20 69 6e 74 65 72 66 61 63  size()] interfac
22720 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  e returns the si
22730 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c 6f  ze of the.** blo
22740 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74  b in bytes..*/.t
22750 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
22760 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74  lite3_blob sqlit
22770 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_blob;../*.** 
22780 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41  CAPI3REF: Open A
22790 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d   BLOB For Increm
227a0 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20  ental I/O.**.** 
227b0 4f 70 65 6e 20 61 20 68 61 6e 64 6c 65 20 74 6f  Open a handle to
227c0 20 74 68 65 20 62 6c 6f 62 20 6c 6f 63 61 74 65   the blob locate
227d0 64 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20  d in row iRow,, 
227e0 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20  column zColumn, 
227f0 0a 2a 2a 20 74 61 62 6c 65 20 7a 54 61 62 6c 65  .** table zTable
22800 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62   in database zDb
22810 2e 20 69 2e 65 2e 20 74 68 65 20 73 61 6d 65 20  . i.e. the same 
22820 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c 64 0a  blob that would.
22830 2a 2a 20 62 65 20 73 65 6c 65 63 74 65 64 20 62  ** be selected b
22840 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  y:.**.** <pre>.*
22850 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f  *     SELECT zCo
22860 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54  lumn FROM zDb.zT
22870 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77 69 64  able WHERE rowid
22880 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72   = iRow;.** </pr
22890 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e>.**.** If the 
228a0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
228b0 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
228c0 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20   blob is opened 
228d0 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61 6e 64  for .** read and
228e0 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 49   write access. I
228f0 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68  f it is zero, th
22900 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64  e blob is opened
22910 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20 61 63   for read .** ac
22920 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  cess..**.** On s
22930 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
22940 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OK] is returned 
22950 61 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20  and the new .** 
22960 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
22970 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73 20  blob handle] is 
22980 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c  written to *ppBl
22990 6f 62 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65  ob..** Otherwise
229a0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
229b0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a  s returned and .
229c0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69  ** any value wri
229d0 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20  tten to *ppBlob 
229e0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
229f0 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ed by the caller
22a00 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  ..** This functi
22a10 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61 74 61  on sets the data
22a20 62 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f  base-handle erro
22a30 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
22a40 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65  ge.** accessible
22a50 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
22a60 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71  rcode()] and [sq
22a70 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
22a80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
22a90 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c  blob_open(.  sql
22aa0 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63  ite3*,.  const c
22ab0 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73  har *zDb,.  cons
22ac0 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a  t char *zTable,.
22ad0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
22ae0 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33  olumn,.  sqlite3
22af0 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69  _int64 iRow,.  i
22b00 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69  nt flags,.  sqli
22b10 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f  te3_blob **ppBlo
22b20 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  b.);../*.** CAPI
22b30 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42  3REF:  Close A B
22b40 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  LOB Handle.**.**
22b50 20 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b   Close an open [
22b60 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
22b70 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2f 0a  lob handle]..*/.
22b80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
22b90 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62  _close(sqlite3_b
22ba0 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
22bb0 41 50 49 33 52 45 46 3a 20 20 52 65 74 75 72 6e  API3REF:  Return
22bc0 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20   The Size Of An 
22bd0 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20  Open BLOB.**.** 
22be0 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
22bf0 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20  in bytes of the 
22c00 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c 65 20  blob accessible 
22c10 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a 2a 2a  via the open .**
22c20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
22c30 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61   blob-handle] pa
22c40 73 73 65 64 20 61 73 20 61 6e 20 61 72 67 75 6d  ssed as an argum
22c50 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
22c60 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73  te3_blob_bytes(s
22c70 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
22c80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22c90 20 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d    Read Data From
22ca0 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
22cb0 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tally.**.** This
22cc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
22cd0 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66  d to read data f
22ce0 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20  rom an open .** 
22cf0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
22d00 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74  blob-handle] int
22d10 6f 20 61 20 63 61 6c 6c 65 72 20 73 75 70 70 6c  o a caller suppl
22d20 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e  ied buffer..** n
22d30 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
22d40 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62  re copied into b
22d50 75 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f 6d 20  uffer.** z from 
22d60 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73  the open blob, s
22d70 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
22d80 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a  t iOffset..**.**
22d90 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c   On success, SQL
22da0 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
22db0 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61  ed. Otherwise, a
22dc0 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
22dd0 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65 72 72  ROR | SQLite err
22de0 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  or code] or an.*
22df0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  * [SQLITE_IOERR_
22e00 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
22e10 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
22e20 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  eturned..*/.int 
22e30 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
22e40 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  d(sqlite3_blob *
22e50 2c 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e  , void *z, int n
22e60 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a  , int iOffset);.
22e70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22e80 20 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74    Write Data Int
22e90 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  o A BLOB Increme
22ea0 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69  ntally.**.** Thi
22eb0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
22ec0 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61  ed to write data
22ed0 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a   into an open .*
22ee0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
22ef0 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 66  | blob-handle] f
22f00 72 6f 6d 20 61 20 75 73 65 72 20 73 75 70 70 6c  rom a user suppl
22f10 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e  ied buffer..** n
22f20 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
22f30 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74  re copied from t
22f40 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69  he buffer.** poi
22f50 6e 74 65 64 20 74 6f 20 62 79 20 7a 20 69 6e 74  nted to by z int
22f60 6f 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c  o the open blob,
22f70 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
22f80 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
22f90 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
22fa0 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68  e3_blob | blob-h
22fb0 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73  andle] passed as
22fc0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
22fd0 65 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  ent.** was not o
22fe0 70 65 6e 65 64 20 66 6f 72 20 77 72 69 74 69 6e  pened for writin
22ff0 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72  g (the flags par
23000 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
23010 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a  e3_blob_open()].
23020 2a 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20 74  *** was zero), t
23030 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
23040 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  urns [SQLITE_REA
23050 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  DONLY]..**.** Th
23060 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
23070 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  only modify the 
23080 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20  contents of the 
23090 62 6c 6f 62 2c 20 69 74 20 69 73 0a 2a 2a 20 6e  blob, it is.** n
230a0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69  ot possible to i
230b0 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65  ncrease the size
230c0 20 6f 66 20 61 20 62 6c 6f 62 20 75 73 69 6e 67   of a blob using
230d0 20 74 68 69 73 20 41 50 49 2e 20 49 66 0a 2a 2a   this API. If.**
230e0 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20   offset iOffset 
230f0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62  is less than n b
23100 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e  ytes from the en
23110 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a  d of the blob, .
23120 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
23130 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
23140 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
23150 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  tten..**.** On s
23160 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f  uccess, SQLITE_O
23170 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f  K is returned. O
23180 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a  therwise, an .**
23190 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c   [SQLITE_ERROR |
231a0 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f   SQLite error co
231b0 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  de] or an.** [SQ
231c0 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
231d0 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72  | extended error
231e0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
231f0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
23200 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71  e3_blob_write(sq
23210 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f  lite3_blob *, co
23220 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74  nst void *z, int
23230 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   n, int iOffset)
23240 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23250 46 3a 20 20 56 69 72 74 75 61 6c 20 46 69 6c 65  F:  Virtual File
23260 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a   System Objects.
23270 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20  **.** A virtual 
23280 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29  filesystem (VFS)
23290 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   is an [sqlite3_
232a0 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74  vfs] object.** t
232b0 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20  hat SQLite uses 
232c0 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77  to interact.** w
232d0 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ith the underlyi
232e0 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
232f0 74 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69 6c 64  tem.  Most build
23300 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a  s come with a.**
23310 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20   single default 
23320 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72  VFS that is appr
23330 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20  opriate for the 
23340 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
23350 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20  * New VFSes can 
23360 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  be registered an
23370 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73  d existing VFSes
23380 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74   can be unregist
23390 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c  ered..** The fol
233a0 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
233b0 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a  s are provided..
233c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
233d0 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74  3_vfs_find() int
233e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
233f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46   pointer to a VF
23400 53 20 67 69 76 65 6e 20 69 74 73 0a 2a 2a 20 6e  S given its.** n
23410 61 6d 65 2e 20 20 4e 61 6d 65 73 20 61 72 65 20  ame.  Names are 
23420 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 20  case sensitive. 
23430 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
23440 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a 2a 2a  match, a NULL.**
23450 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
23460 72 6e 65 64 2e 20 20 49 66 20 7a 56 66 73 4e 61  rned.  If zVfsNa
23470 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  me is NULL then 
23480 74 68 65 20 64 65 66 61 75 6c 74 20 0a 2a 2a 20  the default .** 
23490 56 46 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e  VFS is returned.
234a0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73  .**.** New VFSes
234b0 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 20   are registered 
234c0 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73  with sqlite3_vfs
234d0 5f 72 65 67 69 73 74 65 72 28 29 2e 20 20 45 61  _register().  Ea
234e0 63 68 0a 2a 2a 20 6e 65 77 20 56 46 53 20 62 65  ch.** new VFS be
234f0 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c  comes the defaul
23500 74 20 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b  t VFS if the mak
23510 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65  eDflt flag is se
23520 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20 56  t..** The same V
23530 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  FS can be regist
23540 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
23550 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75  mes without inju
23560 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20 61  ry..** To make a
23570 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69  n existing VFS i
23580 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20  nto the default 
23590 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74  VFS, register it
235a0 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74   again.** with t
235b0 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67  he makeDflt flag
235c0 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69   set.  If two di
235d0 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69  fferent VFSes wi
235e0 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e  th the.** same n
235f0 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72  ame are register
23600 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ed, the behavior
23610 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
23620 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72  If a.** VFS is r
23630 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61  egistered with a
23640 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55   name that is NU
23650 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73  LL or an empty s
23660 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74  tring,.** then t
23670 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
23680 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  ndefined..** .**
23690 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46   Unregister a VF
236a0 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74  S with the sqlit
236b0 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
236c0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  r() interface..*
236d0 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 6c 74  * If the default
236e0 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73 74   VFS is unregist
236f0 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46  ered, another VF
23700 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a  S is chosen as.*
23710 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20  * the default.  
23720 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74  The choice for t
23730 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61 72  he new VFS is ar
23740 62 69 74 72 61 72 79 2e 0a 2a 2f 0a 73 71 6c 69  bitrary..*/.sqli
23750 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33  te3_vfs *sqlite3
23760 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20  _vfs_find(const 
23770 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b  char *zVfsName);
23780 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73  .int sqlite3_vfs
23790 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65  _register(sqlite
237a0 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65  3_vfs*, int make
237b0 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74  Dflt);.int sqlit
237c0 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
237d0 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b  r(sqlite3_vfs*);
237e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
237f0 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20  : Mutexes.**.** 
23800 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
23810 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
23820 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a  nes for thread.*
23830 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  * synchronizatio
23840 6e 2e 20 20 54 68 6f 75 67 68 20 74 68 65 79 20  n.  Though they 
23850 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
23860 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
23870 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65   by SQLite, code
23880 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
23890 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  nst SQLite is.**
238a0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73   permitted to us
238b0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
238c0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
238d0 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  he SQLite source
238e0 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d   code contains m
238f0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
23900 74 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66 20 74  tations .** of t
23910 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69  hese mutex routi
23920 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72  nes.  An appropr
23930 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iate implementat
23940 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74  ion.** is select
23950 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
23960 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
23970 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
23980 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
23990 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
239a0 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
239b0 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  core:.**.** <ul>
239c0 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
239d0 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c  E_MUTEX_OS2.** <
239e0 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
239f0 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c  EX_PTHREAD.** <l
23a00 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
23a10 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20  X_W32.** <li>   
23a20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f  SQLITE_MUTEX_NOO
23a30 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  P.** </ul>.**.**
23a40 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45   The SQLITE_MUTE
23a50 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74  X_NOOP implement
23a60 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f  ation is a set o
23a70 66 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20 74  f routines .** t
23a80 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c  hat does no real
23a90 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20   locking and is 
23aa0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
23ab0 75 73 65 20 69 6e 20 0a 2a 2a 20 61 20 73 69 6e  use in .** a sin
23ac0 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70  gle-threaded app
23ad0 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53  lication.  The S
23ae0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c  QLITE_MUTEX_OS2,
23af0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
23b00 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51  _PTHREAD, and SQ
23b10 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69  LITE_MUTEX_W32 i
23b20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
23b30 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74  * are appropriat
23b40 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 6f 73 2f  e for use on os/
23b50 32 2c 20 75 6e 69 78 2c 20 61 6e 64 20 77 69 6e  2, unix, and win
23b60 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  dows..** .** If 
23b70 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
23b80 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
23b90 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
23ba0 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
23bb0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
23bc0 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
23bd0 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
23be0 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
23bf0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
23c00 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
23c10 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 20 54   the library.  T
23c20 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e 74 65  he.** mutex inte
23c30 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 64  rface routines d
23c40 65 66 69 6e 65 64 20 68 65 72 65 20 62 65 63 6f  efined here beco
23c50 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a 20 72  me external.** r
23c60 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74 68 65  eferences in the
23c70 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
23c80 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c 65 6d  for which implem
23c90 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73  entations.** mus
23ca0 74 20 62 65 20 70 72 6f 76 69 64 65 64 20 62 79  t be provided by
23cb0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
23cc0 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69 74 79  .  This facility
23cd0 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20 61 70   allows an.** ap
23ce0 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 6c  plication that l
23cf0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c  inks against SQL
23d00 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65 20 69  ite to provide i
23d10 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a 2a 20  ts own mutex.** 
23d20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
23d30 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
23d40 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 69   modify the SQLi
23d50 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  te core..**.** T
23d60 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
23d70 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  _alloc() routine
23d80 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77   allocates a new
23d90 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65  .** mutex and re
23da0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
23db0 74 6f 20 69 74 2e 20 20 49 66 20 69 74 20 72 65  to it.  If it re
23dc0 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  turns NULL.** th
23dd0 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  at means that a 
23de0 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20  mutex could not 
23df0 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53  be allocated.  S
23e00 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e  QLite.** will un
23e10 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61  wind its stack a
23e20 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  nd return an err
23e30 6f 72 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  or.  The argumen
23e40 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
23e50 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73  mutex_alloc() is
23e60 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
23e70 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a  teger constants:
23e80 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
23e90 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
23ea0 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20  X_FAST.** <li>  
23eb0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
23ec0 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  URSIVE.** <li>  
23ed0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
23ee0 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c  TIC_MASTER.** <l
23ef0 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
23f00 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c  _STATIC_MEM.** <
23f10 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
23f20 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a  X_STATIC_MEM2.**
23f30 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
23f40 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a  TEX_STATIC_PRNG.
23f50 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
23f60 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
23f70 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
23f80 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f  The first two co
23f90 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73 71  nstants cause sq
23fa0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
23fb0 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a  c() to create.**
23fc0 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 54   a new mutex.  T
23fd0 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20  he new mutex is 
23fe0 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53  recursive when S
23ff0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
24000 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64  RSIVE.** is used
24010 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61   but not necessa
24020 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c  rily so when SQL
24030 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69  ITE_MUTEX_FAST i
24040 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  s used..** The m
24050 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
24060 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
24070 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74  d to make a dist
24080 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
24090 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
240a0 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51  RECURSIVE and SQ
240b0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
240c0 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  if it does.** no
240d0 74 20 77 61 6e 74 20 74 6f 2e 20 20 42 75 74 20  t want to.  But 
240e0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
240f0 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75 72   request a recur
24100 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a  sive mutex in.**
24110 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74 20   cases where it 
24120 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65  really needs one
24130 2e 20 20 49 66 20 61 20 66 61 73 74 65 72 20 6e  .  If a faster n
24140 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74  on-recursive mut
24150 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ex.** implementa
24160 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
24170 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c  e on the host pl
24180 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65  atform, the mute
24190 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d  x subsystem.** m
241a0 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 63 68  ight return such
241b0 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70   a mutex in resp
241c0 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d  onse to SQLITE_M
241d0 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a  UTEX_FAST..**.**
241e0 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77   The other allow
241f0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ed parameters to
24200 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
24210 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75  lloc() each retu
24220 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  rn.** a pointer 
24230 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65  to a static pree
24240 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20  xisting mutex.  
24250 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75 74 65  Four static mute
24260 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  xes are.** used 
24270 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  by the current v
24280 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
24290 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
242a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
242b0 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  may add addition
242c0 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  al static mutexe
242d0 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78  s.  Static mutex
242e0 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72  es are for inter
242f0 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
24300 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c  Lite only.  Appl
24310 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
24320 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73  e SQLite mutexes
24330 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f   should.** use o
24340 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20  nly the dynamic 
24350 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64  mutexes returned
24360 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   by SQLITE_MUTEX
24370 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49  _FAST or.** SQLI
24380 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
24390 56 45 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  VE..**.** Note t
243a0 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68  hat if one of th
243b0 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  e dynamic mutex 
243c0 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49  parameters (SQLI
243d0 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
243e0 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   or SQLITE_MUTEX
243f0 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75  _RECURSIVE) is u
24400 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33  sed then sqlite3
24410 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a  _mutex_alloc().*
24420 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66  * returns a diff
24430 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65  erent mutex on e
24440 76 65 72 79 20 63 61 6c 6c 2e 20 20 42 75 74 20  very call.  But 
24450 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 20 0a  for the static .
24460 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20  ** mutex types, 
24470 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69  the same mutex i
24480 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76  s returned on ev
24490 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61  ery call that ha
244a0 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79  s.** the same ty
244b0 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  pe number..**.**
244c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
244d0 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
244e0 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
244f0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
24500 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
24510 6d 75 74 65 78 2e 20 20 53 51 4c 69 74 65 20 69  mutex.  SQLite i
24520 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61  s careful to dea
24530 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a  llocate every.**
24540 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74   dynamic mutex t
24550 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73  hat it allocates
24560 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d  .  The dynamic m
24570 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20  utexes must not 
24580 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65 20 77 68  be in .** use wh
24590 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c  en they are deal
245a0 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70  located.  Attemp
245b0 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61  ting to dealloca
245c0 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d  te a static.** m
245d0 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20  utex results in 
245e0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
245f0 6f 72 2e 20 20 53 51 4c 69 74 65 20 6e 65 76 65  or.  SQLite neve
24600 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a  r deallocates.**
24610 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e   a static mutex.
24620 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24630 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
24640 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
24650 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65  ex_try() routine
24660 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20  s attempt.** to 
24670 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 20  enter a mutex.  
24680 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
24690 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 74  d is already wit
246a0 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a  hin the mutex,.*
246b0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
246c0 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f  enter() will blo
246d0 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  ck and sqlite3_m
246e0 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20  utex_try() will 
246f0 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
24700 5f 42 55 53 59 2e 20 20 54 68 65 20 73 71 6c 69  _BUSY.  The sqli
24710 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
24720 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24730 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 75  s SQLITE_OK.** u
24740 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65  pon successful e
24750 6e 74 72 79 2e 20 20 4d 75 74 65 78 65 73 20 63  ntry.  Mutexes c
24760 72 65 61 74 65 64 20 75 73 69 6e 67 20 53 51 4c  reated using SQL
24770 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
24780 49 56 45 20 63 61 6e 0a 2a 2a 20 62 65 20 65 6e  IVE can.** be en
24790 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
247a0 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65  imes by the same
247b0 20 74 68 72 65 61 64 2e 20 20 49 6e 20 73 75 63   thread.  In suc
247c0 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20  h cases the,.** 
247d0 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78  mutex must be ex
247e0 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75  ited an equal nu
247f0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65  mber of times be
24800 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72  fore another thr
24810 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72  ead.** can enter
24820 2e 20 20 49 66 20 74 68 65 20 73 61 6d 65 20 74  .  If the same t
24830 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65  hread tries to e
24840 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 20 6b  nter any other k
24850 69 6e 64 20 6f 66 20 6d 75 74 65 78 0a 2a 2a 20  ind of mutex.** 
24860 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
24870 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
24880 75 6e 64 65 66 69 6e 65 64 2e 20 20 20 53 51 4c  undefined.   SQL
24890 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65  ite will never e
248a0 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62  xhibit.** such b
248b0 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f  ehavior in its o
248c0 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65  wn use of mutexe
248d0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
248e0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
248f0 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74 73  () routine exits
24900 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77 61   a mutex that wa
24910 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
24920 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20 73  entered by the s
24930 61 6d 65 20 74 68 72 65 61 64 2e 20 20 54 68 65  ame thread.  The
24940 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
24950 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65  undefined if the
24960 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75   mutex is not cu
24970 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
24980 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e  by the.** callin
24990 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e  g thread or is n
249a0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c  ot currently all
249b0 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20  ocated.  SQLite 
249c0 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f  will.** never do
249d0 20 65 69 74 68 65 72 2e 0a 2a 2a 0a 2a 2a 20 53   either..**.** S
249e0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
249f0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20  3_mutex_held()] 
24a00 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  and [sqlite3_mut
24a10 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a  ex_notheld()]..*
24a20 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  /.sqlite3_mutex 
24a30 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  *sqlite3_mutex_a
24a40 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
24a50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
24a60 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ee(sqlite3_mutex
24a70 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
24a80 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c  _mutex_enter(sql
24a90 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e  ite3_mutex*);.in
24aa0 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
24ab0 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  try(sqlite3_mute
24ac0 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  x*);.void sqlite
24ad0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71  3_mutex_leave(sq
24ae0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a  lite3_mutex*);..
24af0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24b00 4d 75 74 65 78 20 56 65 72 69 66 63 61 74 69 6f  Mutex Verifcatio
24b10 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
24b20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
24b30 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71  ex_held() and sq
24b40 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
24b50 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a  eld() routines.*
24b60 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  * are intended f
24b70 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73  or use inside as
24b80 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
24b90 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  s.  The SQLite c
24ba0 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65  ore.** never use
24bb0 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  s these routines
24bc0 20 65 78 63 65 70 74 20 69 6e 73 69 64 65 20 61   except inside a
24bd0 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64 20 61  n assert() and a
24be0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
24bf0 72 65 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f  re advised to fo
24c00 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66  llow the lead of
24c10 20 74 68 65 20 63 6f 72 65 2e 20 20 54 68 65 20   the core.  The 
24c20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f  core only.** pro
24c30 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61  vides implementa
24c40 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20  tions for these 
24c50 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74  routines when it
24c60 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
24c70 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
24c80 44 45 42 55 47 20 66 6c 61 67 2e 20 20 45 78 74  DEBUG flag.  Ext
24c90 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c  ernal mutex impl
24ca0 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
24cb0 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64  re only required
24cc0 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73   to provide thes
24cd0 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51  e routines if SQ
24ce0 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a  LITE_DEBUG is.**
24cf0 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20   defined and if 
24d00 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65  NDEBUG is not de
24d10 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
24d20 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  se routines shou
24d30 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  ld return true i
24d40 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74  f the mutex in t
24d50 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  heir argument.**
24d60 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20   is held or not 
24d70 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65  held, respective
24d80 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69  ly, by the calli
24d90 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  ng thread..**.**
24da0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
24db0 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69  ion is not requi
24dc0 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20  red to provided 
24dd0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
24de0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
24df0 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b  at actually work
24e00 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6d 70 6c  ..** If the impl
24e10 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
24e20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b  not provide work
24e30 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ing.** versions 
24e40 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
24e50 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20  s, it should at 
24e60 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74  least provide st
24e70 75 62 73 0a 2a 2a 20 74 68 61 74 20 61 6c 77 61  ubs.** that alwa
24e80 79 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  ys return true s
24e90 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20  o that one does 
24ea0 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73  not get spurious
24eb0 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e 20 66 61  .** assertion fa
24ec0 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  ilures..**.** If
24ed0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
24ee0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
24ef0 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  eld() is a NULL 
24f00 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20  pointer then.** 
24f10 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  the routine shou
24f20 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 54 68  ld return 1.  Th
24f30 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72  is seems counter
24f40 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65  -intuitive since
24f50 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20  .** clearly the 
24f60 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20  mutex cannot be 
24f70 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20  held if it does 
24f80 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20  not exist.  But 
24f90 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f  the.** the reaso
24fa0 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73  n the mutex does
24fb0 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65   not exist is be
24fc0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20  cause the build 
24fd0 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20  is not.** using 
24fe0 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65  mutexes.  And we
24ff0 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65   do not want the
25000 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69   assert() contai
25010 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  ning the.** call
25020 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
25030 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c  x_held() to fail
25040 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  , so a non-zero 
25050 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65  return is.** the
25060 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69   appropriate thi
25070 6e 67 20 74 6f 20 64 6f 2e 20 20 54 68 65 20 73  ng to do.  The s
25080 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
25090 68 65 6c 64 28 29 20 0a 2a 2a 20 69 6e 74 65 72  held() .** inter
250a0 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f  face should also
250b0 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67   return 1 when g
250c0 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  iven a NULL poin
250d0 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ter..*/.int sqli
250e0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73  te3_mutex_held(s
250f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
25100 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
25110 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65  x_notheld(sqlite
25120 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a  3_mutex*);../*.*
25130 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
25140 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54 68  x Types.**.** Th
25150 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
25160 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66  _alloc()] interf
25170 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ace takes a sing
25180 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77  le argument.** w
25190 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74  hich is one of t
251a0 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
251b0 73 74 61 6e 74 73 2e 0a 2a 2f 0a 23 64 65 66 69  stants..*/.#defi
251c0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
251d0 46 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20  FAST            
251e0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
251f0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
25200 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  E        1.#defi
25210 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
25220 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20  STATIC_MASTER   
25230 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
25240 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
25250 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73  EM       3  /* s
25260 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
25270 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25280 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
25290 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 73  EM2      4  /* s
252a0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
252b0 65 6d 6f 72 79 28 29 20 2a 2f 0a 23 64 65 66 69  emory() */.#defi
252c0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
252d0 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20  STATIC_PRNG     
252e0 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72   5  /* sqlite3_r
252f0 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69  andom() */.#defi
25300 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
25310 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20  STATIC_LRU      
25320 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20   6  /* lru page 
25330 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  list */../*.** C
25340 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 76  API3REF: Low-Lev
25350 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 61  el Control Of Da
25360 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a  tabase Files.**.
25370 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
25380 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
25390 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
253a0 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f  a direct call to
253b0 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e   the.** xFileCon
253c0 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20  trol method for 
253d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
253e0 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
253f0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
25400 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
25410 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66  database identif
25420 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
25430 64 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  d argument.  The
25440 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
25450 64 61 74 61 62 61 73 65 20 69 73 20 74 68 65 20  database is the 
25460 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
25470 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 79   the database by
25480 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
25490 22 6c 61 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d  "lang_attach.htm
254a0 6c 22 3e 41 54 54 41 43 48 3c 2f 61 3e 20 53 51  l">ATTACH</a> SQ
254b0 4c 20 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f  L command that o
254c0 70 65 6e 65 64 20 74 68 65 0a 2a 2a 20 64 61 74  pened the.** dat
254d0 61 62 61 73 65 2e 20 20 54 6f 20 63 6f 6e 74 72  abase.  To contr
254e0 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  ol the main data
254f0 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74  base file, use t
25500 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a  he name "main".*
25510 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * or a NULL poin
25520 74 65 72 2e 20 20 54 68 65 20 74 68 69 72 64 20  ter.  The third 
25530 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
25540 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 72 6f  eters to this ro
25550 75 74 69 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73  utine.** are pas
25560 73 65 64 20 64 69 72 65 63 74 6c 79 20 74 68 72  sed directly thr
25570 6f 75 67 68 20 74 6f 20 74 68 65 20 73 65 63 6f  ough to the seco
25580 6e 64 20 61 6e 64 20 74 68 69 72 64 20 70 61 72  nd and third par
25590 61 6d 65 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68  ameters of.** th
255a0 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
255b0 65 74 68 6f 64 2e 20 20 54 68 65 20 72 65 74 75  ethod.  The retu
255c0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
255d0 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20  xFileControl.** 
255e0 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74  method becomes t
255f0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
25600 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
25610 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 65  .**.** If the se
25620 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
25630 7a 44 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f  zDbName) does no
25640 74 20 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65  t match the name
25650 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20   of any.** open 
25660 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74  database file, t
25670 68 65 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  hen SQLITE_ERROR
25680 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
25690 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  his error.** cod
256a0 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65  e is not remembe
256b0 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74  red and will not
256c0 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20   be recalled by 
256d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
256e0 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
256f0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 20 54  e3_errmsg()].  T
25700 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46  he underlying xF
25710 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
25720 64 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20  d might.** also 
25730 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52  return SQLITE_ER
25740 52 4f 52 2e 20 20 54 68 65 72 65 20 69 73 20 6e  ROR.  There is n
25750 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67  o way to disting
25760 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20  uish between.** 
25770 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62  an incorrect zDb
25780 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49  Name and an SQLI
25790 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20  TE_ERROR return 
257a0 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79  from the underly
257b0 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74  ing.** xFileCont
257c0 72 6f 6c 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a  rol method..**.*
257d0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
257e0 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
257f0 41 54 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ATE].*/.int sqli
25800 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
25810 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
25820 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20   char *zDbName, 
25830 69 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a  int op, void*);.
25840 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 74 68 65 20  ./*.** Undo the 
25850 68 61 63 6b 20 74 68 61 74 20 63 6f 6e 76 65 72  hack that conver
25860 74 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ts floating poin
25870 74 20 74 79 70 65 73 20 74 6f 20 69 6e 74 65 67  t types to integ
25880 65 72 20 66 6f 72 0a 2a 2a 20 62 75 69 6c 64 73  er for.** builds
25890 20 6f 6e 20 70 72 6f 63 65 73 73 6f 72 73 20 77   on processors w
258a0 69 74 68 6f 75 74 20 66 6c 6f 61 74 69 6e 67 20  ithout floating 
258b0 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2e 0a 2a  point support..*
258c0 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
258d0 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f  OMIT_FLOATING_PO
258e0 49 4e 54 0a 23 20 75 6e 64 65 66 20 64 6f 75 62  INT.# undef doub
258f0 6c 65 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  le.#endif..#ifde
25900 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 7d 20  f __cplusplus.} 
25910 20 2f 2a 20 45 6e 64 20 6f 66 20 74 68 65 20 27   /* End of the '
25920 65 78 74 65 72 6e 20 22 43 22 27 20 62 6c 6f 63  extern "C"' bloc
25930 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64  k */.#endif.#end
25940 69 66 0a                                         if.