/ Hex Artifact Content
Login

Artifact 3844177d389d58bd4a8be4ee81eefb01a084ed72:


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 36 39 20 32 30 30 37 2f  in,v 1.269 2007/
05f0: 31 31 2f 30 35 20 31 37 3a 35 34 3a 31 37 20 64  11/05 17:54:17 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 73 74 72 61 69 6e 74 20 76 69  to constraint vi
2f60: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
2f70: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
2f80: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
2f90: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
2fa0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2fb0: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
2fc0: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
2fd0: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
2fe0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2ff0: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
3000: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
3010: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
3020: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
3030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
3040: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
3050: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
3060: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
3070: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
3080: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
3090: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
30a0: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
30b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30c0: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
30d0: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
30e0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
30f0: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
3100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3110: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
3120: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
3130: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
3140: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
3150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
3160: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
3170: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
3180: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
3190: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
31a0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
31b0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
31c0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
31d0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
31e0: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
31f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
3200: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3210: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
3220: 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 49 6e 20   Codes.**.** In 
3230: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
3240: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
3250: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
3260: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
3270: 69 6e 74 65 67 65 72 0a 2a 2a 20 72 65 73 75 6c  integer.** resul
3280: 74 20 63 6f 64 65 73 20 64 65 73 63 72 69 62 65  t codes describe
3290: 64 20 61 74 20 72 65 73 75 6c 74 2d 63 6f 64 65  d at result-code
32a0: 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  s.  However, exp
32b0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
32c0: 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f  n that.** many o
32d0: 66 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  f these result c
32e0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75  odes are too cou
32f0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
3300: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
3310: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
3320: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
3330: 72 6f 62 6c 65 6d 73 20 61 73 20 75 73 65 72 73  roblems as users
3340: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
3350: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
3360: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
3370: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
3380: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
3390: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
33a0: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
33b0: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
33c0: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
33d0: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
33e0: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
33f0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
3400: 20 65 72 72 6f 72 73 2e 20 20 54 68 65 20 65 78   errors.  The ex
3410: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3420: 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  des are enabled 
3430: 28 6f 72 20 64 69 73 61 62 6c 65 64 29 20 66 6f  (or disabled) fo
3440: 72 20 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62  r .** each datab
3450: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
3460: 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  n using the [sql
3470: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
3480: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50  sult_codes()] AP
3490: 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f  I..** .** Some o
34a0: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
34b0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
34c0: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
34d0: 20 61 62 6f 76 65 2e 0a 2a 2a 20 57 65 20 65 78   above..** We ex
34e0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
34f0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
3500: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
3510: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
3520: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
3530: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
3540: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3550: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
3560: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
3570: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
3580: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
3590: 51 4c 69 74 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  QLite..** .** Th
35a0: 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20  e symbolic name 
35b0: 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20  for an extended 
35c0: 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61  result code alwa
35d0: 79 73 20 63 6f 6e 74 61 69 6e 73 20 61 20 72 65  ys contains a re
35e0: 6c 61 74 65 64 0a 2a 2a 20 70 72 69 6d 61 72 79  lated.** primary
35f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20   result code as 
3600: 61 20 70 72 65 66 69 78 2e 20 20 50 72 69 6d 61  a prefix.  Prima
3610: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ry result codes 
3620: 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65  contain a single
3630: 0a 2a 2a 20 22 5f 22 20 63 68 61 72 61 63 74 65  .** "_" characte
3640: 72 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65 73  r.  Extended res
3650: 75 6c 74 20 63 6f 64 65 73 20 63 6f 6e 74 61 69  ult codes contai
3660: 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f  n two or more "_
3670: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
3680: 20 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c   The numeric val
3690: 75 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65  ue of an extende
36a0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63 61  d result code ca
36b0: 6e 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  n be converted t
36c0: 6f 20 69 74 73 0a 2a 2a 20 63 6f 72 72 65 73 70  o its.** corresp
36d0: 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72  onding primary r
36e0: 65 73 75 6c 74 20 63 6f 64 65 20 62 79 20 6d 61  esult code by ma
36f0: 73 6b 69 6e 67 20 6f 66 66 20 74 68 65 20 6c 6f  sking off the lo
3700: 77 65 72 20 38 20 62 79 74 65 73 2e 0a 2a 2a 0a  wer 8 bytes..**.
3710: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b  ** The SQLITE_OK
3720: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c   result code wil
3730: 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e  l never be exten
3740: 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c  ded.  It will al
3750: 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74  ways.** be exact
3760: 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66  ly zero..*/.#def
3770: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3780: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 28  _READ          (
3790: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
37a0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
37b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
37c0: 54 5f 52 45 41 44 20 20 20 20 28 53 51 4c 49 54  T_READ    (SQLIT
37d0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
37e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
37f0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
3800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3810: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  RR | (3<<8)).#de
3820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3830: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
3840: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3850: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
3860: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
3870: 5f 46 53 59 4e 43 20 20 20 20 20 28 53 51 4c 49  _FSYNC     (SQLI
3880: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
3890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
38a0: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
38b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
38c0: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
38d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
38e0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
38f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3900: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
3910: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e   SQLITE_IOERR_UN
3920: 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  LOCK        (SQL
3930: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
3940: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3950: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
3960: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3970: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
3980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3990: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
39a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
39b0: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
39c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
39d0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 28 53  BLOCKED       (S
39e0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
39f0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
3a00: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45  QLITE_IOERR_NOME
3a10: 4d 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  M         (SQLIT
3a20: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
3a30: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
3a40: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
3a50: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
3a60: 6e 73 0a 2a 2a 0a 2a 2a 20 43 6f 6d 62 69 6e 61  ns.**.** Combina
3a70: 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 6f 6c 6c  tion of the foll
3a80: 6f 77 69 6e 67 20 62 69 74 20 76 61 6c 75 65 73  owing bit values
3a90: 20 61 72 65 20 75 73 65 64 20 61 73 20 74 68 65   are used as the
3aa0: 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65  .** third argume
3ab0: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
3ac0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
3ad0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 61  terface and.** a
3ae0: 73 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  s fourth argumen
3af0: 74 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  t to the xOpen m
3b00: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20  ethod of the.** 
3b10: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
3b20: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2f 0a 23 64 65 66  ject..**.*/.#def
3b30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3b40: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
3b50: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
3b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3b70: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
3b80: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
3b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3ba0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
3bb0: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
3bc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3bd0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
3be0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
3bf0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3c00: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
3c10: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
3c20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3c30: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
3c40: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
3c50: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3c60: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
3c70: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
3c80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3c90: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
3ca0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
3cb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3cc0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
3cd0: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
3ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3cf0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
3d00: 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66   0x00001000.#def
3d10: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3d20: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
3d30: 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65 66   0x00002000.#def
3d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3d50: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
3d60: 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a   0x00004000../*.
3d70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
3d80: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
3d90: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
3da0: 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65  eviceCapabilitie
3db0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
3dc0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
3dd0: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
3de0: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
3df0: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
3e00: 74 6f 72 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  tor of the follo
3e10: 77 69 6e 67 0a 2a 2a 20 62 69 74 20 76 61 6c 75  wing.** bit valu
3e20: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
3e30: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
3e40: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
3e50: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
3e60: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
3e70: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
3e80: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
3e90: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
3ea0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
3eb0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
3ec0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
3ed0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
3ee0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
3ef0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
3f00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3f10: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
3f20: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
3f30: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
3f40: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
3f50: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
3f60: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
3f70: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
3f80: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
3f90: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
3fa0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
3fb0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
3fc0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
3fd0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
3fe0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
3ff0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
4000: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
4010: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
4020: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
4030: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
4040: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
4050: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
4060: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4070: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
4080: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
4090: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
40a0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
40b0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
40c0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
40d0: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
40e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
40f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
4100: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
4110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4120: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
4130: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
4140: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4150: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
4160: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
4170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4180: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
4190: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
41a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
41b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
41c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
41d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
41e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
41f0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
4200: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4210: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
4220: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
4230: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4240: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
4250: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
4260: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4270: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
4280: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
4290: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
42a0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
42b0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
42c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
42d0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
42e0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
42f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4300: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
4310: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
4320: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
4330: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  e following inte
4340: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
4350: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
4360: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
4370: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
4380: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
4390: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
43a0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
43b0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
43c0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
43d0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
43e0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
43f0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
4400: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
4410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4420: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
4430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4440: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
4450: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
4460: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
4470: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
4480: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
4490: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
44a0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
44b0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
44c0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
44d0: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
44e0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
44f0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
4500: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20   combination of 
4510: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  the following in
4520: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 0a  teger values as.
4530: 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  ** the second ar
4540: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
4550: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
4560: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
4570: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
4580: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
4590: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
45a0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
45b0: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
45c0: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
45d0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
45e0: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
45f0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53  d.  The SQLITE_S
4600: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 6d 65 61 6e 73  YNC_NORMAL means
4610: 20 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d   .** to use norm
4620: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
4630: 74 69 63 73 2e 20 20 54 68 65 20 53 51 4c 49 54  tics.  The SQLIT
4640: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
4650: 20 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73   means .** to us
4660: 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65  e Mac OS-X style
4670: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
4680: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f  d of fsync()..*/
4690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46a0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
46b0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
46c0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
46d0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
46e0: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
46f0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
4700: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
4710: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4720: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
4730: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
4740: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
4750: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
4760: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
4770: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a   file in the OS.
4780: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  ** interface lay
4790: 65 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  er.  Individual 
47a0: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70  OS interface imp
47b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
47c0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
47d0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
47e0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
47f0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
4800: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
4810: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
4820: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
4830: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
4840: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
4850: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
4860: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
4870: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
4880: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
4890: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
48a0: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
48b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
48c0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
48d0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
48e0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
48f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
4900: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
4910: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
4920: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
4930: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
4940: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
4950: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
4960: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
4970: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
4980: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
4990: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
49a0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74  Open method cont
49b0: 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ains a pointer t
49c0: 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65  o.** an instance
49d0: 20 6f 66 20 74 68 65 20 74 68 69 73 20 6f 62 6a   of the this obj
49e0: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
49f0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 0a 2a 2a  t defines the.**
4a00: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
4a10: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
4a20: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 67 61 69   operations agai
4a30: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
4a40: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  e..**.** The fla
4a50: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
4a60: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
4a70: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
4a80: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
4a90: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
4aa0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
4ab0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
4ac0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 20 20 54 68  l fsync()..*  Th
4ad0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
4ae0: 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d 58 20 73 74  is an.** OS-X st
4af0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
4b00: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
4b10: 41 54 41 20 66 6c 61 67 20 6d 61 79 20 62 65 20  ATA flag may be 
4b20: 4f 52 65 64 20 69 6e 20 74 6f 0a 2a 2a 20 69 6e  ORed in to.** in
4b30: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
4b40: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
4b50: 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74 20 69 74   file and not it
4b60: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
4b70: 20 62 65 0a 2a 2a 20 73 79 6e 63 65 64 2e 0a 2a   be.** synced..*
4b80: 2a 20 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  * .** The intege
4b90: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
4ba0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
4bb0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
4bc0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
4bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
4be0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
4bf0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
4c00: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
4c10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
4c20: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
4c30: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
4c40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
4c50: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
4c60: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
4c70: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
4c80: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
4c90: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
4ca0: 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 20 54 68 65  e lock.  .** The
4cb0: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
4cc0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 6c 6f 6f  ock() method loo
4cd0: 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ks.** to see if 
4ce0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
4cf0: 6e 65 63 74 69 6f 6e 2c 20 65 69 74 68 65 72 20  nection, either 
4d00: 69 6e 20 74 68 69 73 0a 2a 2a 20 70 72 6f 63 65  in this.** proce
4d10: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
4d20: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
4d30: 68 6f 6c 64 69 6e 67 20 61 6e 20 52 45 53 45 52  holding an RESER
4d40: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
4d50: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
4d60: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
4d70: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
4d80: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
4d90: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
4da0: 6c 73 65 20 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a  lse if not..** .
4db0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
4dc0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
4dd0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
4de0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
4df0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
4e00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
4e10: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
4e20: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
4e30: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
4e40: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
4e50: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
4e60: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
4e70: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20   argument.** is 
4e80: 61 6e 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  an integer opcod
4e90: 65 2e 20 20 20 54 68 65 20 74 68 69 72 64 0a 2a  e.   The third.*
4ea0: 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  * argument is a 
4eb0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
4ec0: 77 68 69 63 68 20 69 73 20 69 6e 74 65 6e 64 65  which is intende
4ed0: 64 20 74 6f 20 62 65 20 61 20 70 6f 69 6e 74 65  d to be a pointe
4ee0: 72 0a 2a 2a 20 74 6f 20 61 20 73 74 72 75 63 74  r.** to a struct
4ef0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
4f00: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
4f10: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
4f20: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
4f30: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
4f40: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
4f50: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
4f60: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
4f70: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
4f80: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
4f90: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
4fa0: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
4fb0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
4fc0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
4fd0: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
4fe0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
4ff0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
5000: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
5010: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
5020: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
5030: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
5040: 76 65 73 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  ves opcodes less
5050: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
5060: 73 20 6f 77 6e 20 75 73 65 2e 20 0a 2a 2a 20 41  s own use. .** A
5070: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
5080: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
5090: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
50a0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
50b0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
50c0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
50d0: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
50e0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
50f0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
5100: 64 65 73 20 0a 2a 2a 20 67 72 65 61 74 65 72 20  des .** greater 
5110: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
5120: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a  d conflicts..**.
5130: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
5140: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
5150: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
5160: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
5170: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
5180: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
5190: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
51a0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
51b0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
51c0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
51d0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
51e0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
51f0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
5200: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
5210: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
5220: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
5230: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
5240: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
5250: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
5260: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
5270: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <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 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
52a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
52b0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
52c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
52d0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
52e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
52f0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
5300: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5310: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
5320: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5330: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
5340: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5350: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
5360: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5370: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
5380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5390: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
53a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
53b0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
53c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
53d0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
53e0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
53f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5400: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
5410: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
5420: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
5430: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
5440: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5450: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
5460: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
5470: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
5480: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
5490: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
54a0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
54b0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
54c0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
54d0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
54e0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
54f0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5500: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
5510: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
5520: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
5530: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
5540: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
5550: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
5560: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
5570: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
5580: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
5590: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
55a0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
55b0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
55c0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
55d0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
55e0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
55f0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
5600: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
5610: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
5620: 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
5630: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
5640: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
5650: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
5660: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
5670: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
5680: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
5690: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
56a0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
56b0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
56c0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
56d0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
56e0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
56f0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
5700: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
5710: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
5720: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
5730: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
5740: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
5750: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
5760: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
5770: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
5780: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
5790: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
57a0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
57b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
57c0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
57d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
57e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
57f0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
5800: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
5810: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
5820: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
5830: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
5840: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
5850: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
5860: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
5870: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
5880: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
5890: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
58a0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
58b0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
58c0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
58d0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64  file*);.  /* Add
58e0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
58f0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
5900: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
5910: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
5920: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
5930: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
5940: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
5950: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
5960: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
5970: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
5980: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
5990: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
59a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
59b0: 20 61 6e 64 20 74 6f 20 74 68 65 20 5b 73 71 6c   and to the [sql
59c0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
59d0: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
59e0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  e..**.** The [SQ
59f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
5a00: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
5a10: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
5a20: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
5a30: 6f 64 65 20 63 61 73 65 73 20 74 68 65 20 78 46  ode cases the xF
5a40: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
5a50: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
5a60: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
5a70: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
5a80: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
5a90: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
5aa0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
5ab0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
5ac0: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
5ad0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
5ae0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
5af0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
5b00: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
5b10: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
5b20: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
5b30: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
5b40: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
5b50: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
5b60: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
5b70: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
5b80: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69  SQLITE_TEST.** i
5b90: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64  s defined..*/.#d
5ba0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
5bb0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
5bc0: 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      1../*.** CAP
5bd0: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
5be0: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  dle.**.** The mu
5bf0: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
5c00: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
5c10: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
5c20: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
5c30: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
5c40: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
5c50: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
5c60: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
5c70: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
5c80: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
5c90: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
5ca0: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
5cb0: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
5cc0: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
5cd0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
5ce0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
5cf0: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
5d00: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
5d10: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
5d20: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
5d30: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
5d40: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
5d50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
5d60: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
5d70: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
5d80: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
5d90: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
5da0: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
5db0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  the.** SQLite co
5dc0: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
5dd0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
5de0: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
5df0: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
5e00: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
5e10: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
5e20: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
5e30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 56 65 72  ..**.** The iVer
5e40: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
5e50: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
5e60: 79 20 62 65 20 6c 61 72 67 65 72 20 66 6f 72 20  y be larger for 
5e70: 66 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  future.** versio
5e80: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
5e90: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
5ea0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
5eb0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
5ec0: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
5ed0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
5ee0: 63 72 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  creased..**.** T
5ef0: 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c  he szOsFile fiel
5f00: 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  d is the size of
5f10: 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20   the subclassed 
5f20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a  [sqlite3_file].*
5f30: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
5f40: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
5f50: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
5f60: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
5f70: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
5f80: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
5f90: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 76  .** Registered v
5fa0: 66 73 20 6d 6f 64 75 6c 65 73 20 61 72 65 20 6b  fs modules are k
5fb0: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
5fc0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
5fd0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
5fe0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
5ff0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
6000: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
6010: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
6020: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
6030: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
6040: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
6050: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
6060: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
6070: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
6080: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
6090: 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  st..**.** The pN
60a0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
60b0: 20 6f 6e 6c 79 20 66 69 65 6c 64 73 20 69 6e 20   only fields in 
60c0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
60d0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68  .** structure th
60e0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  at SQLite will e
60f0: 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c  ver modify.  SQL
6100: 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63  ite will only ac
6110: 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66  cess.** or modif
6120: 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69  y this field whi
6130: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
6140: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
6150: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
6160: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
6170: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
6180: 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65  thing within the
6190: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
61a0: 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20  object once the 
61b0: 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20  object has been 
61c0: 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a  registered..**.*
61d0: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
61e0: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
61f0: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
6200: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
6210: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
6220: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
6230: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51  odules..**.** SQ
6240: 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e  Lite will guaran
6250: 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69  tee that the zFi
6260: 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67 20 70 61  lename string pa
6270: 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e  ssed to.** xOpen
6280: 28 29 20 69 73 20 61 20 66 75 6c 6c 20 70 61 74  () is a full pat
6290: 68 6e 61 6d 65 20 61 73 20 67 65 6e 65 72 61 74  hname as generat
62a0: 65 64 20 62 79 20 78 46 75 6c 6c 50 61 74 68 6e  ed by xFullPathn
62b0: 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61  ame() and.** tha
62c0: 74 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  t the string wil
62d0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
62e0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
62f0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
6300: 6c 6c 65 64 2e 20 20 53 6f 20 74 68 65 20 5b 73  lled.  So the [s
6310: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
6320: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
6330: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
6340: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
6350: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
6360: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
6370: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  e reason..**.** 
6380: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
6390: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 73  nt to xOpen() is
63a0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
63b0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  lags argument.**
63c0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
63d0: 6e 5f 76 32 28 29 5d 2e 20 20 49 66 20 5b 73 71  n_v2()].  If [sq
63e0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
63f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
6400: 28 29 5d 0a 2a 2a 20 69 73 20 75 73 65 64 2c 20  ()].** is used, 
6410: 74 68 65 6e 20 66 6c 61 67 73 20 69 73 20 5b 53  then flags is [S
6420: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
6430: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
6440: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a  OPEN_CREATE]..**
6450: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
6460: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
6470: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
6480: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
6490: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
64a0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
64b0: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
64c0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
64d0: 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a  e.** set..** .**
64e0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
64f0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
6500: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
6510: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
6520: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
6530: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
6540: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
6550: 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  * .** <ul>.** <l
6560: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
6570: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
6580: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
6590: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_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 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
65c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
65d0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
65e0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
65f0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
6600: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
6610: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6620: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
6630: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
6640: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
6650: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
6660: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
6670: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
6680: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
6690: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
66a0: 67 65 73 20 74 68 65 20 77 61 79 20 69 74 20 64  ges the way it d
66b0: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
66c0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
66d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
66e0: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
66f0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
6700: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
6710: 62 61 63 6b 2c 20 6d 69 67 68 74 20 6d 61 6b 65  back, might make
6720: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
6730: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
6740: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
6750: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
6760: 61 72 65 0a 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f  are.** also a no
6770: 2d 6f 70 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  -op.  Any attemp
6780: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
6790: 75 72 6e 61 6c 20 72 65 74 75 72 6e 20 53 51 4c  urnal return SQL
67a0: 49 54 45 5f 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72  ITE_IOERR..** Or
67b0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
67c0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
67d0: 69 7a 65 20 74 68 65 20 61 20 64 61 74 61 62 61  ize the a databa
67e0: 73 65 20 66 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20  se file will.** 
67f0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
6800: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
6810: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
6820: 20 61 20 72 61 6e 64 6f 6d 20 6f 72 64 65 72 0a   a random order.
6830: 2a 2a 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  ** and set up it
6840: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
6850: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20  accordingly..** 
6860: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
6870: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
6880: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
6890: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
68a0: 6e 0a 2a 2a 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20  n.** method:.** 
68b0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
68c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
68d0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
68e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
68f0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
6900: 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  </ul>.** .** The
6910: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
6920: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
6930: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
6940: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
6950: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
6960: 20 63 6c 6f 73 65 64 2e 20 20 54 68 69 73 20 77   closed.  This w
6970: 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 73 65  ill always be se
6980: 74 20 66 6f 72 20 54 45 4d 50 20 0a 2a 2a 20 64  t for TEMP .** d
6990: 61 74 61 62 61 73 65 73 20 61 6e 64 20 6a 6f 75  atabases and jou
69a0: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
69b0: 62 6a 6f 75 72 6e 61 6c 73 2e 20 20 54 68 65 20  bjournals.  The 
69c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
69d0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
69e0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
69f0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
6a00: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
6a10: 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73 20  e access.  This 
6a20: 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72 20  flag is set for 
6a30: 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74  all files except
6a40: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e  .** for the main
6a50: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
6a60: 2a 2a 20 0a 2a 2a 20 53 70 61 63 65 20 74 6f 20  ** .** Space to 
6a70: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
6a80: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
6a90: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
6aa0: 20 74 68 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d   third .** argum
6ab0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ent to xOpen is 
6ac0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 63 61 6c  allocated by cal
6ad0: 6c 65 72 20 28 74 68 65 20 53 51 4c 69 74 65 20  ler (the SQLite 
6ae0: 63 6f 72 65 29 2e 20 0a 2a 2a 20 73 7a 4f 73 46  core). .** szOsF
6af0: 69 6c 65 20 62 79 74 65 73 20 61 72 65 20 61 6c  ile bytes are al
6b00: 6c 6f 63 61 74 65 64 20 66 6f 72 20 74 68 69 73  located for this
6b10: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 78 4f   object.  The xO
6b20: 70 65 6e 20 6d 65 74 68 6f 64 0a 2a 2a 20 66 69  pen method.** fi
6b30: 6c 6c 73 20 69 6e 20 74 68 65 20 61 6c 6c 6f 63  lls in the alloc
6b40: 61 74 65 64 20 73 70 61 63 65 2e 0a 2a 2a 20 0a  ated space..** .
6b50: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
6b60: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
6b70: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
6b80: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
6b90: 20 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72   .** to test for
6ba0: 20 74 68 65 20 65 78 69 73 74 61 6e 63 65 20 6f   the existance o
6bb0: 66 20 61 20 66 69 6c 65 2c 0a 2a 2a 20 6f 72 20  f a file,.** or 
6bc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
6bd0: 45 41 44 57 52 49 54 45 5d 20 74 6f 20 74 65 73  EADWRITE] to tes
6be0: 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61  t to see.** if a
6bf0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
6c00: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
6c10: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
6c20: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
6c30: 73 74 20 74 6f 20 73 65 65 20 69 66 20 61 20 66  st to see if a f
6c40: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
6c50: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
6c60: 69 6c 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a  ile can be a .**
6c70: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a   directory..** .
6c80: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  ** SQLite will a
6c90: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
6ca0: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
6cb0: 6d 65 2b 31 20 62 79 74 65 20 66 6f 72 0a 2a 2a  me+1 byte for.**
6cc0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
6cd0: 65 72 73 20 66 6f 72 20 78 47 65 74 54 65 6d 70  ers for xGetTemp
6ce0: 6e 61 6d 65 20 61 6e 64 20 78 46 75 6c 6c 50 61  name and xFullPa
6cf0: 74 68 6e 61 6d 65 2e 20 54 68 65 20 65 78 61 63  thname. The exac
6d00: 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65  t.** size of the
6d10: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 69   output buffer i
6d20: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
6d30: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
6d40: 62 6f 74 68 20 0a 2a 2a 20 6d 65 74 68 6f 64 73  both .** methods
6d50: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
6d60: 62 75 66 66 65 72 20 69 73 20 6e 6f 74 20 6c 61  buffer is not la
6d70: 72 67 65 20 65 6e 6f 75 67 68 2c 20 53 51 4c 49  rge enough, SQLI
6d80: 54 45 5f 43 41 4e 54 4f 50 45 4e 0a 2a 2a 20 73  TE_CANTOPEN.** s
6d90: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
6da0: 64 2e 20 41 73 20 74 68 69 73 20 69 73 20 68 61  d. As this is ha
6db0: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
6dc0: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
6dd0: 2c 0a 2a 2a 20 76 66 73 20 69 6d 70 6c 65 6d 65  ,.** vfs impleme
6de0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
6df0: 65 6e 64 65 76 6f 75 72 20 74 6f 20 70 72 65 76  endevour to prev
6e00: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
6e10: 69 6e 67 20 0a 2a 2a 20 6d 78 50 61 74 68 6e 61  ing .** mxPathna
6e20: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
6e30: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
6e40: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61  ..** .** The xRa
6e50: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
6e60: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  ep(), and xCurre
6e70: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61  ntTime() interfa
6e80: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73  ces.** are not s
6e90: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
6ea0: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
6eb0: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
6ec0: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
6ed0: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
6ee0: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
6ef0: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
6f00: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
6f10: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
6f20: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
6f30: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
6f40: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
6f50: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
6f60: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
6f70: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
6f80: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
6f90: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
6fa0: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c 65  ed.  The.** xSle
6fb0: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
6fc0: 65 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  e the calling th
6fd0: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
6fe0: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
6ff0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
7000: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
7010: 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   The xCurrentTim
7020: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
7030: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
7040: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
7050: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
7060: 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74  nd.** time..*/.t
7070: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7080: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
7090: 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71  3_vfs;.struct sq
70a0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
70b0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
70c0: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
70d0: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
70e0: 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  er */.  int szOs
70f0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
7100: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
7110: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
7120: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
7130: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
7140: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
7150: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
7160: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
7170: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
7180: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
7190: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
71a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
71b0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
71c0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
71d0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
71e0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
71f0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
7200: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
7210: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
7220: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
7230: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
7240: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
7250: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
7260: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
7270: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
7280: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
7290: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
72a0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
72b0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
72c0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
72d0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
72e0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
72f0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
7300: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
7310: 28 2a 78 47 65 74 54 65 6d 70 6e 61 6d 65 29 28  (*xGetTempname)(
7320: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
7330: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
7340: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
7350: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
7360: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7370: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
7380: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
7390: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
73a0: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
73b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
73c0: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
73d0: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
73e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
73f0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
7400: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
7410: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
7420: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
7430: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
7440: 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  ol);.  void (*xD
7450: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
7460: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
7470: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
7480: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
7490: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
74a0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
74b0: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
74c0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
74d0: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
74e0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
74f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
7500: 75 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77  uble*);.  /* New
7510: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
7520: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
7530: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
7540: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
7550: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
7560: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
7570: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b  s happens. */.};
7580: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7590: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
75a0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
75b0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
75c0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
75d0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
75e0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
75f0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
7600: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
7610: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
7620: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
7630: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
7640: 6b 69 6e 64 20 6f 66 20 77 68 61 74 20 6b 69 6e  kind of what kin
7650: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
7660: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
7670: 68 6f 64 20 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e  hod is.** lookin
7680: 67 20 66 6f 72 2e 20 20 57 69 74 68 20 53 51 4c  g for.  With SQL
7690: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
76a0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
76b0: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
76c0: 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66  checks to see if
76d0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
76e0: 2e 20 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  .  With SQLITE_A
76f0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
7700: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
7710: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 74 6f  method checks to
7720: 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65   see if the file
7730: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
7740: 65 0a 2a 2a 20 61 6e 64 20 77 72 69 74 61 62 6c  e.** and writabl
7750: 65 2e 20 20 57 69 74 68 20 53 51 4c 49 54 45 5f  e.  With SQLITE_
7760: 41 43 43 45 53 53 5f 52 45 41 44 20 74 68 65 20  ACCESS_READ the 
7770: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
7780: 2a 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20  * checks to see 
7790: 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  if the file is r
77a0: 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66  eadable..*/.#def
77b0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
77c0: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
77d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
77e0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a  ESS_READWRITE 1.
77f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
7800: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
7810: 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  2../*.** CAPI3RE
7820: 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
7830: 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
7840: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
7850: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e   This routine en
7860: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
7870: 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
7880: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
7890: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
78a0: 64 65 73 5d 20 66 65 61 74 75 72 65 2e 0a 2a 2a  des] feature..**
78b0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 53 51 4c   By default, SQL
78c0: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
78d0: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 6f   return one of o
78e0: 6e 6c 79 20 32 36 20 69 6e 74 65 67 65 72 0a 2a  nly 26 integer.*
78f0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72  * [SQLITE_OK | r
7900: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 57  esult codes].  W
7910: 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
7920: 75 6c 74 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65  ult codes.** are
7930: 20 65 6e 61 62 6c 65 64 20 62 79 20 74 68 69 73   enabled by this
7940: 20 72 6f 75 74 69 6e 65 2c 20 74 68 65 20 72 65   routine, the re
7950: 70 65 74 6f 69 72 65 20 6f 66 20 72 65 73 75 6c  petoire of resul
7960: 74 20 63 6f 64 65 73 20 63 61 6e 20 62 65 0a 2a  t codes can be.*
7970: 2a 20 6d 75 63 68 20 6c 61 72 67 65 72 20 61 6e  * much larger an
7980: 64 20 63 61 6e 20 28 68 6f 70 65 66 75 6c 6c 79  d can (hopefully
7990: 29 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  ) provide more d
79a0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
79b0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ion.** about the
79c0: 20 63 61 75 73 65 20 6f 66 20 61 6e 20 65 72 72   cause of an err
79d0: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  or..**.** The se
79e0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
79f0: 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65   a boolean value
7a00: 20 74 68 61 74 20 74 75 72 6e 73 20 65 78 74 65   that turns exte
7a10: 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
7a20: 6f 64 65 73 20 6f 6e 20 61 6e 64 20 6f 66 66 2e  odes on and off.
7a30: 20 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c    Extended resul
7a40: 74 20 63 6f 64 65 73 20 61 72 65 20 6f 66 66 20  t codes are off 
7a50: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 0a 2a  by default for.*
7a60: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
7a70: 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
7a80: 6c 64 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  lder versions of
7a90: 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
7aa0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
7ab0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
7ac0: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
7ad0: 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
7ae0: 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
7af0: 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 45 61 63   Rowid.**.** Eac
7b00: 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
7b10: 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
7b20: 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
7b30: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 6b 65  igned integer ke
7b40: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 68 65 20  y.** called the 
7b50: 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77  "rowid". The row
7b60: 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
7b70: 69 6c 61 62 6c 65 20 61 73 20 61 6e 20 75 6e 64  ilable as an und
7b80: 65 63 6c 61 72 65 64 0a 2a 2a 20 63 6f 6c 75 6d  eclared.** colum
7b90: 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
7ba0: 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 2e 20  ID, or _ROWID_. 
7bb0: 20 49 66 20 74 68 65 20 74 61 62 6c 65 20 68 61   If the table ha
7bc0: 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 0a 2a 2a  s a column of.**
7bd0: 20 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52   type INTEGER PR
7be0: 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74  IMARY KEY then t
7bf0: 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 61 6e  hat column is an
7c00: 6f 74 68 65 72 20 61 6e 20 61 6c 69 61 73 20 66  other an alias f
7c10: 6f 72 20 74 68 65 0a 2a 2a 20 72 6f 77 69 64 2e  or the.** rowid.
7c20: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
7c30: 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
7c40: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73  rowid of the mos
7c50: 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
7c60: 66 75 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 0a  ful INSERT into.
7c70: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
7c80: 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73  from the databas
7c90: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 67 69 76  e connection giv
7ca0: 65 6e 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  en in the first 
7cb0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  .** argument.  I
7cc0: 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
7cd0: 69 6e 73 65 72 74 73 20 68 61 76 65 20 65 76 65  inserts have eve
7ce0: 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
7cf0: 69 73 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  is database.** c
7d00: 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
7d10: 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
7d20: 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20  ** If an INSERT 
7d30: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
7d40: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
7d50: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0a 2a  e rowid of the.*
7d60: 2a 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 69  * inserted row i
7d70: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
7d80: 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f  is routine as lo
7d90: 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
7da0: 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 2e  r.** is running.
7db0: 20 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74    But once the t
7dc0: 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65  rigger terminate
7dd0: 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
7de0: 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73  urned.** by this
7df0: 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
7e00: 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c   to the last val
7e10: 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f  ue inserted befo
7e20: 72 65 20 74 68 65 0a 2a 2a 20 74 72 69 67 67 65  re the.** trigge
7e30: 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  r fired..**.** A
7e40: 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 66 61  n INSERT that fa
7e50: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
7e60: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
7e70: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
7e80: 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20  ccessful insert 
7e90: 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
7ea0: 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
7eb0: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
7ec0: 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73  * routine.  Thus
7ed0: 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
7ee0: 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
7ef0: 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
7f00: 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
7f10: 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
7f20: 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
7f30: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
7f40: 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
7f50: 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
7f60: 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
7f70: 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52    When INSERT OR
7f80: 20 52 45 50 4c 41 43 45 20 0a 2a 2a 20 65 6e 63   REPLACE .** enc
7f90: 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
7fa0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
7fb0: 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
7fc0: 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
7fd0: 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
7fe0: 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
7ff0: 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
8000: 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
8010: 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
8020: 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
8030: 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
8040: 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
8050: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
8060: 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
8070: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
8080: 65 72 20 74 68 72 65 61 64 20 64 6f 65 73 20 61  er thread does a
8090: 20 6e 65 77 20 69 6e 73 65 72 74 20 6f 6e 20 74   new insert on t
80a0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
80b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
80c0: 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
80d0: 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  e is running and
80e0: 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
80f0: 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
8100: 77 69 64 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  wid,.** then the
8110: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
8120: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
8130: 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 73   undefined..*/.s
8140: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
8150: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
8160: 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
8170: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8180: 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
8190: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
81a0: 66 69 65 64 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  fied.**.** This 
81b0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
81c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
81d0: 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
81e0: 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
81f0: 2a 20 28 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  * (or inserted o
8200: 72 20 64 65 6c 65 74 65 64 29 20 62 79 20 74 68  r deleted) by th
8210: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 53 51  e most recent SQ
8220: 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4f 6e  L statement.  On
8230: 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68  ly.** changes th
8240: 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20  at are directly 
8250: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
8260: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
8270: 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74   or.** DELETE st
8280: 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
8290: 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
82a0: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
82b0: 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72  y.** triggers ar
82c0: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20  e not counted.  
82d0: 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
82e0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
82f0: 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f  ] function.** to
8300: 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20   find the total 
8310: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
8320: 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  s including chan
8330: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
8340: 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 57 69  iggers..**.** Wi
8350: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
8360: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 20   a trigger, the 
8370: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
8380: 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
8390: 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 6f 20  be.** called to 
83a0: 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
83b0: 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
83c0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
83d0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
83e0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
83f0: 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
8400: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
8410: 6f 64 79 20 6f 66 20 74 68 65 20 74 72 69 67 67  ody of the trigg
8420: 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 63 68  er..**.** All ch
8430: 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
8440: 64 2c 20 65 76 65 6e 20 69 66 20 74 68 65 79 20  d, even if they 
8450: 77 65 72 65 20 6c 61 74 65 72 20 75 6e 64 6f 6e  were later undon
8460: 65 20 62 79 20 61 0a 2a 2a 20 52 4f 4c 4c 42 41  e by a.** ROLLBA
8470: 43 4b 20 6f 72 20 41 42 4f 52 54 2e 20 20 45 78  CK or ABORT.  Ex
8480: 63 65 70 74 2c 20 63 68 61 6e 67 65 73 20 61 73  cept, changes as
8490: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 72  sociated with cr
84a0: 65 61 74 69 6e 67 20 61 6e 64 0a 2a 2a 20 64 72  eating and.** dr
84b0: 6f 70 70 69 6e 67 20 74 61 62 6c 65 73 20 61 72  opping tables ar
84c0: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
84d0: 2a 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 62 61  *.** If a callba
84e0: 63 6b 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69  ck invokes [sqli
84f0: 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
8500: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
8510: 72 65 63 75 72 73 69 76 65 6c 79 2c 0a 2a 2a 20  recursively,.** 
8520: 74 68 65 6e 20 74 68 65 20 63 68 61 6e 67 65 73  then the changes
8530: 20 69 6e 20 74 68 65 20 69 6e 6e 65 72 2c 20 72   in the inner, r
8540: 65 63 75 72 73 69 76 65 20 63 61 6c 6c 20 61 72  ecursive call ar
8550: 65 20 63 6f 75 6e 74 65 64 20 74 6f 67 65 74 68  e counted togeth
8560: 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 63  er.** with the c
8570: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6f 75  hanges in the ou
8580: 74 65 72 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  ter call..**.** 
8590: 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
85a0: 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44  s the command "D
85b0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
85c0: 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52  " without a WHER
85d0: 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64  E clause.** by d
85e0: 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72  ropping and recr
85f0: 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65  eating the table
8600: 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68  .  (This is much
8610: 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69   faster than goi
8620: 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e  ng.** through an
8630: 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76  d deleting indiv
8640: 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66  idual elements f
8650: 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20  rom the table.) 
8660: 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74   Because of.** t
8670: 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  his optimization
8680: 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75  , the change cou
8690: 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46  nt for "DELETE F
86a0: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20  ROM table" will 
86b0: 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72  be.** zero regar
86c0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d  dless of the num
86d0: 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20  ber of elements 
86e0: 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e  that were origin
86f0: 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74  ally in the.** t
8700: 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20  able. To get an 
8710: 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
8720: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
8730: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
8740: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
8750: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
8760: 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20   instead..**.** 
8770: 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
8780: 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
8790: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
87a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
87b0: 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  ** while this ro
87c0: 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
87d0: 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
87e0: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72   value of this r
87f0: 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64  outine.** is und
8800: 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
8810: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
8820: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
8830: 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
8840: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
8850: 4d 6f 64 69 66 69 65 64 0a 2a 2a 2a 0a 2a 2a 20  Modified.***.** 
8860: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
8870: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
8880: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
8890: 73 20 74 68 61 74 20 68 61 76 65 20 62 65 65 6e  s that have been
88a0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 62 79 20  .** modified by 
88b0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
88c0: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
88d0: 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 64 61  nts since the da
88e0: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 0a 2a 2a  tabase handle.**
88f0: 20 77 61 73 20 6f 70 65 6e 65 64 2e 20 54 68 69   was opened. Thi
8900: 73 20 69 6e 63 6c 75 64 65 73 20 55 50 44 41 54  s includes UPDAT
8910: 45 2c 20 49 4e 53 45 52 54 20 61 6e 64 20 44 45  E, INSERT and DE
8920: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
8930: 65 78 65 63 75 74 65 64 0a 2a 2a 20 61 73 20 70  executed.** as p
8940: 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
8950: 72 6f 67 72 61 6d 73 2e 20 41 6c 6c 20 63 68 61  rograms. All cha
8960: 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
8970: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 0a   as soon as the.
8980: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
8990: 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
89a0: 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
89b0: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
89c0: 6e 64 6c 65 20 69 73 0a 2a 2a 20 70 61 73 73 65  ndle is.** passe
89d0: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
89e0: 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
89f0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
8a00: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
8a10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
8a20: 6e 67 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  nge()] interface
8a30: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
8a40: 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f  mplements the co
8a50: 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52  mmand "DELETE FR
8a60: 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75  OM table" withou
8a70: 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65  t a WHERE clause
8a80: 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20  .** by dropping 
8a90: 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74  and recreating t
8aa0: 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73  he table.  (This
8ab0: 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20   is much faster 
8ac0: 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68  than going.** th
8ad0: 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69  rough and deleti
8ae0: 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c  ng individual el
8af0: 65 6d 65 6e 74 73 20 66 6f 72 6d 20 74 68 65 20  ements form the 
8b00: 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65  table.)  Because
8b10: 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69   of.** this opti
8b20: 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68  mization, the ch
8b30: 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22  ange count for "
8b40: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
8b50: 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65  e" will be.** ze
8b60: 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ro regardless of
8b70: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
8b80: 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72  lements that wer
8b90: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20  e originally in 
8ba0: 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f  the.** table. To
8bb0: 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65   get an accurate
8bc0: 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75   count of the nu
8bd0: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c  mber of rows del
8be0: 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45  eted, use.** "DE
8bf0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20  LETE FROM table 
8c00: 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64  WHERE 1" instead
8c10: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
8c20: 65 72 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  er thread makes 
8c30: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
8c40: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
8c50: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
8c60: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
8c70: 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
8c80: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
8c90: 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  f this routine.*
8ca0: 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
8cb0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
8cc0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
8cd0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
8ce0: 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
8cf0: 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
8d00: 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68  g Query.**.** Th
8d10: 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
8d20: 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
8d30: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
8d40: 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
8d50: 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
8d60: 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
8d70: 6e 69 74 79 2e 20 20 54 68 69 73 20 72 6f 75 74  nity.  This rout
8d80: 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
8d90: 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
8da0: 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
8db0: 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
8dc0: 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
8dd0: 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
8de0: 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
8df0: 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
8e00: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
8e10: 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
8e20: 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73  y..**.** It is s
8e30: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
8e40: 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
8e50: 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
8e60: 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
8e70: 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
8e80: 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
8e90: 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
8ea0: 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
8eb0: 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
8ec0: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
8ed0: 65 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  e with a databas
8ee0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
8ef0: 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
8f00: 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
8f10: 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
8f20: 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
8f30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 20  ..**.** The SQL 
8f40: 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
8f50: 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
8f60: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
8f70: 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
8f80: 20 49 66 20 61 6e 20 69 6e 74 65 72 72 75 70 74   If an interrupt
8f90: 65 64 20 6f 70 65 72 61 74 69 6f 6e 20 77 61 73  ed operation was
8fa0: 20 61 6e 20 75 70 64 61 74 65 20 74 68 61 74 20   an update that 
8fb0: 69 73 20 69 6e 73 69 64 65 20 61 6e 0a 2a 2a 20  is inside an.** 
8fc0: 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
8fd0: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
8fe0: 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
8ff0: 6e 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  n will be rolled
9000: 0a 2a 2a 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  .** back automat
9010: 69 63 61 6c 6c 79 2e 0a 2a 2f 0a 76 6f 69 64 20  ically..*/.void 
9020: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
9030: 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
9040: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
9050: 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
9060: 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
9070: 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
9080: 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
9090: 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65  turn true if the
90a0: 20 67 69 76 65 6e 20 69 6e 70 75 74 20 73 74 72   given input str
90b0: 69 6e 67 20 63 6f 6d 70 72 69 73 65 73 0a 2a 2a  ing comprises.**
90c0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d   one or more com
90d0: 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
90e0: 65 6e 74 73 2e 20 46 6f 72 20 74 68 65 20 73 71  ents. For the sq
90f0: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
9100: 20 63 61 6c 6c 2c 0a 2a 2a 20 74 68 65 20 70 61   call,.** the pa
9110: 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
9120: 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
9130: 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 20 46   UTF-8 string. F
9140: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
9150: 6d 70 6c 65 74 65 31 36 28 29 2c 20 61 20 6e 75  mplete16(), a nu
9160: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 6d 61 63  l-terminated mac
9170: 68 69 6e 65 20 62 79 74 65 20 6f 72 64 65 72 20  hine byte order 
9180: 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
9190: 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
91a0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
91b0: 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  es are useful fo
91c0: 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  r command-line i
91d0: 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
91e0: 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
91f0: 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
9200: 78 74 20 66 6f 72 6d 73 20 6f 6e 65 20 6f 72 20  xt forms one or 
9210: 6d 6f 72 65 20 63 6f 6d 70 6c 65 74 65 20 53 51  more complete SQ
9220: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 0a  L statements or.
9230: 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
9240: 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
9250: 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
9260: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 69  the statements i
9270: 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
9280: 72 20 70 61 72 73 69 6e 67 2e 20 54 68 65 20 61  r parsing. The a
9290: 6c 67 6f 72 69 74 68 6d 20 69 73 20 73 69 6d 70  lgorithm is simp
92a0: 6c 65 2e 20 20 49 66 20 74 68 65 20 0a 2a 2a 20  le.  If the .** 
92b0: 6c 61 73 74 20 74 6f 6b 65 6e 20 6f 74 68 65 72  last token other
92c0: 20 74 68 61 6e 20 73 70 61 63 65 73 20 61 6e 64   than spaces and
92d0: 20 63 6f 6d 6d 65 6e 74 73 20 69 73 20 61 20 73   comments is a s
92e0: 65 6d 69 63 6f 6c 6f 6e 2c 20 74 68 65 6e 20 72  emicolon, then r
92f0: 65 74 75 72 6e 20 0a 2a 2a 20 74 72 75 65 2e 20  eturn .** true. 
9300: 20 41 63 74 75 61 6c 6c 79 2c 20 74 68 65 20 61   Actually, the a
9310: 6c 67 6f 72 69 74 68 6d 20 69 73 20 61 20 6c 69  lgorithm is a li
9320: 74 74 6c 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69  ttle more compli
9330: 63 61 74 65 64 20 74 68 61 6e 20 74 68 61 74 0a  cated than that.
9340: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64  ** in order to d
9350: 65 61 6c 20 77 69 74 68 20 74 72 69 67 67 65 72  eal with trigger
9360: 73 2c 20 62 75 74 20 74 68 65 20 62 61 73 69 63  s, but the basic
9370: 20 69 64 65 61 20 69 73 20 74 68 65 20 73 61 6d   idea is the sam
9380: 65 3a 20 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  e:  the.** state
9390: 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 6f 6d 70  ment is not comp
93a0: 6c 65 74 65 20 75 6e 6c 65 73 73 20 69 74 20 65  lete unless it e
93b0: 6e 64 73 20 69 6e 20 61 20 73 65 6d 69 63 6f 6c  nds in a semicol
93c0: 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  on..*/.int sqlit
93d0: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
93e0: 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
93f0: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
9400: 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
9410: 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
9420: 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
9430: 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
9440: 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
9450: 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 54  Y Errors.**.** T
9460: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 64 65 6e  his routine iden
9470: 74 69 66 69 65 73 20 61 20 63 61 6c 6c 62 61 63  tifies a callbac
9480: 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
9490: 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
94a0: 0a 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 6e 20  .** whenever an 
94b0: 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
94c0: 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
94d0: 73 65 20 74 61 62 6c 65 20 0a 2a 2a 20 74 68 61  se table .** tha
94e0: 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
94f0: 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
9500: 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66 20 74 68  locked..** If th
9510: 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
9520: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
9530: 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 28  QLITE_BUSY].** (
9540: 6f 72 20 73 6f 6d 65 74 69 6d 65 73 20 5b 53 51  or sometimes [SQ
9550: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
9560: 45 44 5d 29 0a 2a 2a 20 69 73 20 72 65 74 75 72  ED]).** is retur
9570: 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
9580: 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
9590: 67 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49  g the lock..** I
95a0: 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
95b0: 61 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ack is not NULL,
95c0: 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c   then the.** cal
95d0: 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e  lback will be in
95e0: 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
95f0: 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a  rguments.  The.*
9600: 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  * first argument
9610: 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20   to the handler 
9620: 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
9630: 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
9640: 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
9650: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
9660: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20   this routine.  
9670: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
9680: 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61  ent to.** the ha
9690: 6e 64 6c 65 72 20 69 73 20 74 68 65 20 6e 75 6d  ndler is the num
96a0: 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
96b0: 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
96c0: 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
96d0: 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
96e0: 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 49  locking event. I
96f0: 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
9700: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
9710: 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
9720: 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
9730: 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
9740: 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
9750: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
9760: 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
9770: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
9780: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
9790: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
97a0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
97b0: 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
97c0: 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
97d0: 70 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  pen the.** datab
97e0: 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
97f0: 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
9800: 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
9810: 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
9820: 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
9830: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
9840: 68 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62  hat.** it will b
9850: 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  e invoked when t
9860: 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
9870: 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53  tention..** If S
9880: 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
9890: 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
98a0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
98b0: 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a  could result in.
98c0: 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  ** a deadlock, i
98d0: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  t will return [S
98e0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 6e 73 74  QLITE_BUSY] inst
98f0: 65 61 64 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ead..** Consider
9900: 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
9910: 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
9920: 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
9930: 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
9940: 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
9950: 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
9960: 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
9970: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
9980: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
9990: 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
99a0: 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
99b0: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
99c0: 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
99d0: 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
99e0: 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
99f0: 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
9a00: 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
9a10: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
9a20: 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
9a30: 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
9a40: 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
9a50: 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
9a60: 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
9a70: 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
9a80: 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
9a90: 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
9aa0: 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
9ab0: 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
9ac0: 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
9ad0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
9ae0: 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
9af0: 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
9b00: 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
9b10: 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
9b20: 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
9b30: 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
9b40: 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
9b50: 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
9b60: 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
9b70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
9b80: 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
9b90: 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
9ba0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
9bb0: 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
9bc0: 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
9bd0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 77  IOERR_BLOCKED] w
9be0: 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  hen.** SQLite is
9bf0: 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
9c00: 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
9c10: 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
9c20: 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
9c30: 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
9c40: 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
9c50: 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
9c60: 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
9c70: 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
9c80: 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
9c90: 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
9ca0: 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
9cb0: 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
9cc0: 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
9cd0: 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
9ce0: 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
9cf0: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
9d00: 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
9d10: 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
9d20: 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66  .** readers.  If
9d30: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
9d40: 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
9d50: 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
9d60: 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
9d70: 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
9d80: 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
9d90: 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
9da0: 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
9db0: 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
9dc0: 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
9dd0: 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
9de0: 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
9df0: 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
9e00: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
9e10: 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64    This error cod
9e20: 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66  e promotion.** f
9e30: 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74  orces an automat
9e40: 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74  ic rollback of t
9e50: 68 65 20 63 68 61 6e 67 65 73 2e 20 53 65 65 20  he changes. See 
9e60: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
9e70: 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74  http://www.sqlit
9e80: 65 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f 77 69  e.org/cvstrac/wi
9e90: 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
9ea0: 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
9eb0: 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
9ec0: 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
9ed0: 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
9ee0: 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
9ef0: 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
9f00: 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
9f10: 2a 2a 09 0a 2a 2a 20 53 71 6c 69 74 65 20 69 73  **..** Sqlite is
9f20: 20 72 65 2d 65 6e 74 72 61 6e 74 2c 20 73 6f 20   re-entrant, so 
9f30: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
9f40: 20 6d 61 79 20 73 74 61 72 74 20 61 20 6e 65 77   may start a new
9f50: 20 71 75 65 72 79 2e 20 0a 2a 2a 20 28 49 74 20   query. .** (It 
9f60: 69 73 20 6e 6f 74 20 63 6c 65 61 72 20 77 68 79  is not clear why
9f70: 20 61 6e 79 6f 6e 65 20 77 6f 75 6c 64 20 65 76   anyone would ev
9f80: 65 72 79 20 77 61 6e 74 20 74 6f 20 64 6f 20 74  ery want to do t
9f90: 68 69 73 2c 20 62 75 74 20 69 74 0a 2a 2a 20 69  his, but it.** i
9fa0: 73 20 61 6c 6c 6f 77 65 64 2c 20 69 6e 20 74 68  s allowed, in th
9fb0: 65 6f 72 79 2e 29 20 20 42 75 74 20 74 68 65 20  eory.)  But the 
9fc0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79  busy handler may
9fd0: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 0a 2a   not close the.*
9fe0: 2a 20 64 61 74 61 62 61 73 65 2e 20 20 43 6c 6f  * database.  Clo
9ff0: 73 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  sing the databas
a000: 65 20 66 72 6f 6d 20 61 20 62 75 73 79 20 68 61  e from a busy ha
a010: 6e 64 6c 65 72 20 77 69 6c 6c 20 64 65 6c 65 74  ndler will delet
a020: 65 20 0a 2a 2a 20 64 61 74 61 20 73 74 72 75 63  e .** data struc
a030: 74 75 72 65 73 20 6f 75 74 20 66 72 6f 6d 20 75  tures out from u
a040: 6e 64 65 72 20 74 68 65 20 65 78 65 63 75 74 69  nder the executi
a050: 6e 67 20 71 75 65 72 79 20 61 6e 64 20 77 69 6c  ng query and wil
a060: 6c 20 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72  l .** probably r
a070: 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
a080: 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
a090: 20 6f 74 68 65 72 20 72 75 6e 74 69 6d 65 20 65   other runtime e
a0a0: 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  rror..**.** Ther
a0b0: 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
a0c0: 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
a0d0: 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
a0e0: 65 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a  each database.**
a0f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
a100: 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
a110: 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
a120: 61 6e 79 20 70 72 65 76 69 6f 75 73 20 6f 6e 65  any previous one
a130: 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 63  ..** Note that c
a140: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
a150: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
a160: 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
a170: 20 63 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62 75   clear.** the bu
a180: 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
a190: 2a 20 57 68 65 6e 20 6f 70 65 72 61 74 69 6e 67  * When operating
a1a0: 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61   in [sqlite3_ena
a1b0: 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
a1c0: 20 7c 20 73 68 61 72 65 64 20 63 61 63 68 65 20   | shared cache 
a1d0: 6d 6f 64 65 5d 2c 0a 2a 2a 20 6f 6e 6c 79 20 61  mode],.** only a
a1e0: 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
a1f0: 64 6c 65 72 20 63 61 6e 20 62 65 20 64 65 66 69  dler can be defi
a200: 6e 65 64 20 66 6f 72 20 65 61 63 68 20 64 61 74  ned for each dat
a210: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 53  abase file..** S
a220: 6f 20 69 66 20 74 77 6f 20 64 61 74 61 62 61 73  o if two databas
a230: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 73 68  e connections sh
a240: 61 72 65 20 61 20 73 69 6e 67 6c 65 20 63 61 63  are a single cac
a250: 68 65 2c 20 74 68 65 6e 20 63 68 61 6e 67 69 6e  he, then changin
a260: 67 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  g.** the busy ha
a270: 6e 64 6c 65 72 20 6f 6e 20 6f 6e 65 20 63 6f 6e  ndler on one con
a280: 6e 65 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 73  nection will als
a290: 6f 20 63 68 61 6e 67 65 20 74 68 65 20 62 75 73  o change the bus
a2a0: 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 6e 20  y.** handler in 
a2b0: 74 68 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63  the other connec
a2c0: 74 69 6f 6e 2e 20 20 54 68 65 20 62 75 73 79 20  tion.  The busy 
a2d0: 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b  handler is invok
a2e0: 65 64 0a 2a 2a 20 69 6e 20 74 68 65 20 74 68 72  ed.** in the thr
a2f0: 65 61 64 20 74 68 61 74 20 77 61 73 20 72 75 6e  ead that was run
a300: 6e 69 6e 67 20 77 68 65 6e 20 74 68 65 20 53 51  ning when the SQ
a310: 4c 49 54 45 5f 42 55 53 59 20 77 61 73 20 68 69  LITE_BUSY was hi
a320: 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
a330: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
a340: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
a350: 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
a360: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
a370: 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
a380: 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 54 68  Timeout.**.** Th
a390: 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
a3a0: 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 74  a busy handler t
a3b0: 68 61 74 20 73 6c 65 65 70 73 20 66 6f 72 20 61  hat sleeps for a
a3c0: 20 77 68 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a   while when a.**
a3d0: 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
a3e0: 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 20 77  .  The handler w
a3f0: 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
a400: 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a  le times until .
a410: 2a 2a 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  ** at least "ms"
a420: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
a430: 20 73 6c 65 65 70 69 6e 67 20 68 61 76 65 20 62   sleeping have b
a440: 65 65 6e 20 64 6f 6e 65 2e 20 20 41 66 74 65 72  een done.  After
a450: 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  .** "ms" millise
a460: 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
a470: 67 2c 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  g, the handler r
a480: 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 0a 2a  eturns 0 which.*
a490: 2a 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  * causes [sqlite
a4a0: 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
a4b0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
a4c0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
a4d0: 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
a4e0: 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  ** Calling this 
a4f0: 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
a500: 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
a510: 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
a520: 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
a530: 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
a540: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  rs..**.** There 
a550: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
a560: 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
a570: 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
a580: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
a590: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20 61  onnection.  If a
a5a0: 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
a5b0: 6c 65 72 20 77 61 73 20 64 65 66 69 6e 65 64 20  ler was defined 
a5c0: 20 0a 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c   .** (using [sql
a5d0: 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
a5e0: 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
a5f0: 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
a600: 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
a610: 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
a620: 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2f 0a 69  is cleared..*/.i
a630: 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
a640: 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
a650: 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
a660: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
a670: 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
a680: 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
a690: 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
a6a0: 6e 65 78 74 20 72 6f 75 74 69 6e 65 20 69 73 20  next routine is 
a6b0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
a6c0: 61 70 70 65 72 20 61 72 6f 75 6e 64 20 5b 73 71  apper around [sq
a6d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a  lite3_exec()]..*
a6e0: 2a 20 49 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  * Instead of inv
a6f0: 6f 6b 69 6e 67 20 61 20 75 73 65 72 2d 73 75 70  oking a user-sup
a700: 70 6c 69 65 64 20 63 61 6c 6c 62 61 63 6b 20 66  plied callback f
a710: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74  or each row of t
a720: 68 65 0a 2a 2a 20 72 65 73 75 6c 74 2c 20 74 68  he.** result, th
a730: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 6d 65 6d  is routine remem
a740: 62 65 72 73 20 65 61 63 68 20 72 6f 77 20 6f 66  bers each row of
a750: 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 6d   the result in m
a760: 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65  emory.** obtaine
a770: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
a780: 6d 61 6c 6c 6f 63 28 29 5d 2c 20 74 68 65 6e 20  malloc()], then 
a790: 72 65 74 75 72 6e 73 20 61 6c 6c 20 6f 66 20 74  returns all of t
a7a0: 68 65 20 72 65 73 75 6c 74 20 61 66 74 65 72 20  he result after 
a7b0: 74 68 65 0a 2a 2a 20 71 75 65 72 79 20 68 61 73  the.** query has
a7c0: 20 66 69 6e 69 73 68 65 64 2e 20 0a 2a 2a 0a 2a   finished. .**.*
a7d0: 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c  * As an example,
a7e0: 20 73 75 70 70 6f 73 65 20 74 68 65 20 71 75 65   suppose the que
a7f0: 72 79 20 72 65 73 75 6c 74 20 77 68 65 72 65 20  ry result where 
a800: 74 68 69 73 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a  this table:.**.*
a810: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
a820: 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
a830: 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
a840: 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
a850: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
a860: 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
a870: 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
a880: 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
a890: 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
a8a0: 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
a8b0: 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
a8c0: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
a8d0: 49 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  If the 3rd argum
a8e0: 65 6e 74 20 77 65 72 65 20 26 61 7a 52 65 73 75  ent were &azResu
a8f0: 6c 74 20 74 68 65 6e 20 61 66 74 65 72 20 74 68  lt then after th
a900: 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
a910: 6e 73 0a 2a 2a 20 61 7a 52 65 73 75 6c 74 20 77  ns.** azResult w
a920: 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  ill contain the 
a930: 66 6f 6c 6c 6f 77 69 6e 67 20 64 61 74 61 3a 0a  following data:.
a940: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
a950: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
a960: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
a970: 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
a980: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
a990: 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
a9a0: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
a9b0: 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
a9c0: 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
a9d0: 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
a9e0: 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
a9f0: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
aa00: 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
aa10: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
aa20: 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
aa30: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
aa40: 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
aa50: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
aa60: 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
aa70: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
aa80: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4e  ckquote>.**.** N
aa90: 6f 74 69 63 65 20 74 68 61 74 20 74 68 65 72 65  otice that there
aaa0: 20 69 73 20 61 6e 20 65 78 74 72 61 20 72 6f 77   is an extra row
aab0: 20 6f 66 20 64 61 74 61 20 63 6f 6e 74 61 69 6e   of data contain
aac0: 69 6e 67 20 74 68 65 20 63 6f 6c 75 6d 6e 0a 2a  ing the column.*
aad0: 2a 20 68 65 61 64 65 72 73 2e 20 20 42 75 74 20  * headers.  But 
aae0: 74 68 65 20 2a 6e 72 6f 77 20 72 65 74 75 72 6e  the *nrow return
aaf0: 20 76 61 6c 75 65 20 69 73 20 73 74 69 6c 6c 20   value is still 
ab00: 33 2e 20 20 2a 6e 63 6f 6c 75 6d 6e 20 69 73 0a  3.  *ncolumn is.
ab10: 2a 2a 20 73 65 74 20 74 6f 20 32 2e 20 20 49 6e  ** set to 2.  In
ab20: 20 67 65 6e 65 72 61 6c 2c 20 74 68 65 20 6e 75   general, the nu
ab30: 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
ab40: 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 61 7a 52  nserted into azR
ab50: 65 73 75 6c 74 0a 2a 2a 20 77 69 6c 6c 20 62 65  esult.** will be
ab60: 20 28 28 2a 6e 72 6f 77 29 20 2b 20 31 29 2a 28   ((*nrow) + 1)*(
ab70: 2a 6e 63 6f 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a 2a  *ncolumn)..**.**
ab80: 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
ab90: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
aba0: 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
abb0: 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
abc0: 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74 68  ould .** pass th
abd0: 65 20 72 65 73 75 6c 74 20 64 61 74 61 20 70 6f  e result data po
abe0: 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
abf0: 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
ac00: 20 6f 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72 65   order to .** re
ac10: 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
ac20: 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
ac30: 2d 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  -ed.  Because of
ac40: 20 74 68 65 20 77 61 79 20 74 68 65 20 0a 2a 2a   the way the .**
ac50: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ac60: 28 29 5d 20 68 61 70 70 65 6e 73 2c 20 74 68 65  ()] happens, the
ac70: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
ac80: 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
ac90: 6f 20 63 61 6c 6c 20 0a 2a 2a 20 5b 73 71 6c 69  o call .** [sqli
aca0: 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
acb0: 63 74 6c 79 2e 20 20 4f 6e 6c 79 20 5b 73 71 6c  ctly.  Only [sql
acc0: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
acd0: 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
ace0: 6c 65 61 73 65 20 0a 2a 2a 20 74 68 65 20 6d 65  lease .** the me
acf0: 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
ad00: 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
ad10: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
ad20: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
ad30: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
ad40: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 65 78  from [sqlite3_ex
ad50: 65 63 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ec()]..*/.int sq
ad60: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
ad70: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
ad80: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
ad90: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
ada0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
adb0: 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
adc0: 20 74 6f 20 62 65 20 65 78 65 63 75 74 65 64 20   to be executed 
add0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73  */.  char ***res
ade0: 75 6c 74 70 2c 20 20 20 20 20 20 20 2f 2a 20 52  ultp,       /* R
adf0: 65 73 75 6c 74 20 77 72 69 74 74 65 6e 20 74 6f  esult written to
ae00: 20 61 20 63 68 61 72 20 2a 5b 5d 20 20 74 68 61   a char *[]  tha
ae10: 74 20 74 68 69 73 20 70 6f 69 6e 74 73 20 74 6f  t this points to
ae20: 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c   */.  int *nrow,
ae30: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
ae40: 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
ae50: 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
ae60: 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f  re */.  int *nco
ae70: 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20 20 2f  lumn,          /
ae80: 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
ae90: 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
aea0: 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
aeb0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
aec0: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
aed0: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
aee0: 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
aef0: 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
af00: 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
af10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
af20: 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
af30: 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
af40: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
af50: 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c  tines are workal
af60: 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
af70: 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
af80: 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
af90: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
afa0: 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
afb0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72   The sqlite3_mpr
afc0: 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
afd0: 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
afe0: 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
aff0: 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
b000: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b010: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b020: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
b030: 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
b040: 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
b050: 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
b060: 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
b070: 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
b080: 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69  ()].  Both routi
b090: 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
b0a0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
b0b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
b0c0: 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
b0d0: 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
b0e0: 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
b0f0: 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
b100: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e  string..**.** In
b110: 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
b120: 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
b130: 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
b140: 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
b150: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
b160: 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
b170: 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
b180: 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
b190: 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
b1a0: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
b1b0: 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
b1c0: 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
b1d0: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
b1e0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
b1f0: 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
b200: 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
b210: 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
b220: 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
b230: 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  .  This is an.**
b240: 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
b250: 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
b260: 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
b270: 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
b280: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
b290: 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73  ility.  Note als
b2a0: 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
b2b0: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
b2c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
b2d0: 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
b2e0: 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
b2f0: 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
b300: 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
b310: 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
b320: 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20  ffer.  We admit 
b330: 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
b340: 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
b350: 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
b360: 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
b370: 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
b380: 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
b390: 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
b3a0: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
b3b0: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
b3c0: 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
b3d0: 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
b3e0: 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f  ity..**.** As lo
b3f0: 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
b400: 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
b410: 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
b420: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
b430: 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
b440: 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
b450: 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
b460: 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72  inated.  The fir
b470: 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
b480: 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
b490: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
b4a0: 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
b4b0: 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
b4c0: 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
b4d0: 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
b4e0: 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
b4f0: 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
b500: 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
b510: 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
b520: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
b530: 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
b540: 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
b550: 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
b560: 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
b570: 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
b580: 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
b590: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
b5a0: 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
b5b0: 70 72 69 6e 74 66 20 66 6f 72 6d 61 74 74 69 6e  printf formattin
b5c0: 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
b5d0: 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
b5e0: 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
b5f0: 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
b600: 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
b610: 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e  ** The %q option
b620: 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
b630: 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
b640: 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72  tutes a null-ter
b650: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
b660: 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
b670: 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
b680: 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
b690: 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
b6a0: 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
b6b0: 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
b6c0: 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
b6d0: 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62  iteral.  By doub
b6e0: 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
b6f0: 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
b700: 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
b710: 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
b720: 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
b730: 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
b740: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
b750: 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d   example, so som
b760: 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
b770: 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  e contains text 
b780: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
b790: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
b7a0: 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
b7b0: 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
b7c0: 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
b7d0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
b7e0: 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
b7f0: 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
b800: 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
b810: 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
b820: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
b830: 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
b840: 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
b850: 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
b860: 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
b870: 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
b880: 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
b890: 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
b8a0: 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
b8b0: 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
b8c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
b8d0: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
b8e0: 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
b8f0: 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
b900: 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
b910: 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
b920: 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
b930: 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
b940: 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
b950: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
b960: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
b970: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
b980: 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
b990: 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
b9a0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
b9b0: 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
b9c0: 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
b9d0: 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
b9e0: 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
b9f0: 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
ba00: 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
ba10: 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
ba20: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
ba30: 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
ba40: 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
ba50: 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
ba60: 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
ba70: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
ba80: 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
ba90: 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
baa0: 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
bab0: 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
bac0: 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64  le you.** should
bad0: 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
bae0: 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
baf0: 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
bb00: 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 0a   into a string .
bb10: 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ** literal..**.*
bb20: 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  * The %Q option 
bb30: 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
bb40: 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
bb50: 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
bb60: 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
bb70: 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
bb80: 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72 20 69  al string.  Or i
bb90: 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
bba0: 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a  in the argument.
bbb0: 2a 2a 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  ** list is a NUL
bbc0: 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
bbd0: 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
bbe0: 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
bbf0: 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f  ut single.** quo
bc00: 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66  tes) in place of
bc10: 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20   the %Q option. 
bc20: 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
bc30: 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
bc40: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
bc50: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
bc60: 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
bc70: 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
bc80: 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
bc90: 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
bca0: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
bcb0: 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
bcc0: 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
bcd0: 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
bce0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
bcf0: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
bd00: 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
bd10: 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
bd20: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
bd30: 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
bd40: 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
bd50: 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
bd60: 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
bd70: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22  ter..**.** The "
bd80: 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
bd90: 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63  ption works exac
bda0: 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69  tly like "%s" wi
bdb0: 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
bdc0: 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
bdd0: 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
bde0: 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
bdf0: 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
be00: 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
be10: 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
be20: 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
be30: 72 69 6e 67 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ring..*/.char *s
be40: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
be50: 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
be60: 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
be70: 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
be80: 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
be90: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
bea0: 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
beb0: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
bec0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
bed0: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
bee0: 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
bef0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
bf00: 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
bf10: 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
bf20: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
bf30: 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
bf40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
bf50: 20 6e 65 65 64 73 2e 20 28 53 65 65 20 74 68 65   needs. (See the
bf60: 20 65 78 63 65 70 74 69 6f 6e 20 62 65 6c 6f 77   exception below
bf70: 2e 29 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  .).**.** The def
bf80: 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ault implementat
bf90: 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65  ion.** of the me
bfa0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bfb0: 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 20 74  subsystem uses t
bfc0: 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  he malloc(), rea
bfd0: 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72  lloc().** and fr
bfe0: 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79  ee() provided by
bff0: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
c000: 6c 69 62 72 61 72 79 2e 20 20 48 6f 77 65 76 65  library.  Howeve
c010: 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65  r, if .** SQLite
c020: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
c030: 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  h the following 
c040: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
c050: 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  acro.**.** <bloc
c060: 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4d  kquote> SQLITE_M
c070: 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e  EMORY_SIZE=<i>NN
c080: 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f  N</i> </blockquo
c090: 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20  te>.**.** where 
c0a0: 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e  <i>NNN</i> is an
c0b0: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 20 53   integer, then S
c0c0: 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73  QLite create a s
c0d0: 74 61 74 69 63 0a 2a 2a 20 61 72 72 61 79 20 6f  tatic.** array o
c0e0: 66 20 61 74 20 6c 65 61 73 74 20 3c 69 3e 4e 4e  f at least <i>NN
c0f0: 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73  N</i> bytes in s
c100: 69 7a 65 20 61 6e 64 20 75 73 65 20 74 68 61 74  ize and use that
c110: 20 61 72 72 61 79 0a 2a 2a 20 66 6f 72 20 61 6c   array.** for al
c120: 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
c130: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c140: 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  on needs..**.** 
c150: 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
c160: 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
c170: 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
c180: 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
c190: 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
c1a0: 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
c1b0: 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
c1c0: 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
c1d0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
c1e0: 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
c1f0: 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
c200: 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
c210: 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
c220: 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
c230: 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
c240: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
c250: 63 61 6e 20 62 65 0a 2a 2a 20 75 73 65 64 2e 0a  can be.** used..
c260: 2a 2a 0a 2a 2a 20 3c 62 3e 45 78 63 65 70 74 69  **.** <b>Excepti
c270: 6f 6e 3a 3c 2f 62 3e 20 54 68 65 20 77 69 6e 64  on:</b> The wind
c280: 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
c290: 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
c2a0: 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
c2b0: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
c2c0: 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
c2d0: 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
c2e0: 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
c2f0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
c300: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
c310: 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
c320: 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
c330: 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
c340: 70 61 72 74 69 63 75 6c 61 72 20 77 69 6e 64 6f  particular windo
c350: 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
c360: 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
c370: 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
c380: 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
c390: 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
c3a0: 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
c3b0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
c3c0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
c3d0: 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
c3e0: 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
c3f0: 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
c400: 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
c410: 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
c420: 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
c430: 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
c440: 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
c450: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
c460: 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
c470: 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 49 6e  tistics.**.** In
c480: 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 74 68 65   addition to the
c490: 20 62 61 73 69 63 20 74 68 72 65 65 20 61 6c 6c   basic three all
c4a0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c4b0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
c4c0: 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
c4d0: 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
c4e0: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
c4f0: 29 5d 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  )],.** the memor
c500: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
c510: 73 79 73 74 65 6d 20 69 6e 63 6c 75 64 65 64 20  system included 
c520: 77 69 74 68 20 74 68 65 20 53 51 4c 69 74 65 0a  with the SQLite.
c530: 2a 2a 20 73 6f 75 72 63 65 73 20 70 72 6f 76 69  ** sources provi
c540: 64 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  des the interfac
c550: 65 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  es shown below..
c560: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
c570: 6f 66 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  of these two rou
c580: 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 74 68  tines returns th
c590: 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  e amount of memo
c5a0: 72 79 20 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  ry .** currently
c5b0: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
c5c0: 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
c5d0: 72 65 65 64 29 2e 20 20 54 68 65 20 73 65 63 6f  reed).  The seco
c5e0: 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  nd.** returns th
c5f0: 65 20 6c 61 72 67 65 73 74 20 69 6e 73 74 61 6e  e largest instan
c600: 74 61 6e 65 6f 75 73 20 61 6d 6f 75 6e 74 20 6f  taneous amount o
c610: 66 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a  f outstanding.**
c620: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 68 69   memory.  The hi
c630: 67 68 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  ghwater mark is 
c640: 72 65 73 65 74 20 69 66 20 74 68 65 20 61 72 67  reset if the arg
c650: 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 72 75 65  ument is.** true
c660: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
c670: 65 20 72 65 74 75 72 6e 65 64 20 6d 61 79 20 6f  e returned may o
c680: 72 20 6d 61 79 20 6e 6f 74 20 69 6e 63 6c 75 64  r may not includ
c690: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  e allocation.** 
c6a0: 6f 76 65 72 68 65 61 64 2c 20 64 65 70 65 6e 64  overhead, depend
c6b0: 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 62 75 69  ing on which bui
c6c0: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
c6d0: 6f 63 61 74 6f 72 0a 2a 2a 20 69 6d 70 6c 65 6d  ocator.** implem
c6e0: 65 6e 74 61 74 69 6f 6e 20 69 73 20 75 73 65 64  entation is used
c6f0: 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
c700: 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
c710: 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
c720: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
c730: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
c740: 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
c750: 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
c760: 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
c770: 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
c780: 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 2a 0a 2a   Callbacks.***.*
c790: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
c7a0: 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
c7b0: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
c7c0: 69 74 68 20 74 68 65 20 53 51 4c 69 74 65 20 6c  ith the SQLite l
c7d0: 69 62 72 61 72 79 2e 20 20 0a 2a 2a 20 54 68 65  ibrary.  .** The
c7e0: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
c7f0: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
c800: 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
c810: 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
c820: 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
c830: 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
c840: 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
c850: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
c860: 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
c870: 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
c880: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
c890: 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41  pare16_v2()].  A
c8a0: 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
c8b0: 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
c8c0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
c8d0: 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
c8e0: 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
c8f0: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
c900: 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
c910: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
c920: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
c930: 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
c940: 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
c950: 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74  llowed.  The aut
c960: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
c970: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
c980: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 74 6f 20 61  n SQLITE_OK to a
c990: 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
c9a0: 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
c9b0: 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
c9c0: 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
c9d0: 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
c9e0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
c9f0: 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
ca00: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
ca10: 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
ca20: 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
ca30: 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
ca40: 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
ca50: 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
ca60: 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 44 65 70 65 6e  r.  .**.** Depen
ca70: 64 69 6e 67 20 6f 6e 20 74 68 65 20 61 63 74 69  ding on the acti
ca80: 6f 6e 2c 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  on, the [SQLITE_
ca90: 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c  IGNORE] and [SQL
caa0: 49 54 45 5f 44 45 4e 59 5d 20 72 65 74 75 72 6e  ITE_DENY] return
cab0: 0a 2a 2a 20 63 6f 64 65 73 20 6d 69 67 68 74 20  .** codes might 
cac0: 6d 65 61 6e 20 73 6f 6d 65 74 68 69 6e 67 20 64  mean something d
cad0: 69 66 66 65 72 65 6e 74 20 6f 72 20 74 68 65 79  ifferent or they
cae0: 20 6d 69 67 68 74 20 6d 65 61 6e 20 74 68 65 20   might mean the 
caf0: 73 61 6d 65 0a 2a 2a 20 74 68 69 6e 67 2e 20 20  same.** thing.  
cb00: 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  If the action is
cb10: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
cb20: 6f 20 70 65 72 66 6f 72 6d 20 61 20 64 65 6c 65  o perform a dele
cb30: 74 65 20 6f 70 65 72 74 69 6f 6e 2c 0a 2a 2a 20  te opertion,.** 
cb40: 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  then [SQLITE_IGN
cb50: 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  ORE] and [SQLITE
cb60: 5f 44 45 4e 59 5d 20 62 6f 74 68 20 63 61 75 73  _DENY] both caus
cb70: 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
cb80: 63 6f 6d 70 69 6c 61 74 69 6f 6e 0a 2a 2a 20 74  compilation.** t
cb90: 6f 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  o fail with an e
cba0: 72 72 6f 72 2e 20 20 42 75 74 20 69 66 20 74 68  rror.  But if th
cbb0: 65 20 61 63 74 69 6f 6e 20 69 73 20 74 6f 20 72  e action is to r
cbc0: 65 61 64 20 61 20 73 70 65 63 69 66 69 63 20 63  ead a specific c
cbd0: 6f 6c 75 6d 6e 0a 2a 2a 20 66 72 6f 6d 20 61 20  olumn.** from a 
cbe0: 73 70 65 63 69 66 69 63 20 74 61 62 6c 65 2c 20  specific table, 
cbf0: 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 44 45 4e  then [SQLITE_DEN
cc00: 59 5d 20 77 69 6c 6c 20 63 61 75 73 65 20 74 68  Y] will cause th
cc10: 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 74 61 74  e entire.** stat
cc20: 65 6d 65 6e 74 20 74 6f 20 66 61 69 6c 20 62 75  ement to fail bu
cc30: 74 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  t [SQLITE_IGNORE
cc40: 5d 20 77 69 6c 6c 20 63 61 75 73 65 20 61 20 4e  ] will cause a N
cc50: 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 62 65 0a  ULL value to be.
cc60: 2a 2a 20 72 65 61 64 20 69 6e 73 74 65 61 64 20  ** read instead 
cc70: 6f 66 20 74 68 65 20 61 63 74 75 61 6c 20 63 6f  of the actual co
cc80: 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  lumn value..**.*
cc90: 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
cca0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
ccb0: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
ccc0: 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
ccd0: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
cce0: 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
ccf0: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
cd00: 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
cd10: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
cd20: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
cd30: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
cd40: 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c 49 54  teger .** [SQLIT
cd50: 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
cd60: 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
cd70: 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75  fies the particu
cd80: 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f  lar action.** to
cd90: 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
cda0: 20 54 68 65 20 61 76 61 69 6c 61 62 6c 65 20 61   The available a
cdb0: 63 74 69 6f 6e 20 63 6f 64 65 73 20 61 72 65 0a  ction codes are.
cdc0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  ** [SQLITE_COPY 
cdd0: 7c 20 64 6f 63 75 6d 65 6e 74 65 64 20 73 65 70  | documented sep
cde0: 61 72 61 74 65 6c 79 5d 2e 20 20 54 68 65 20 74  arately].  The t
cdf0: 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
ce00: 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  th.** parameters
ce10: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
ce20: 20 61 72 65 20 73 74 72 69 6e 67 73 20 74 68 61   are strings tha
ce30: 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
ce40: 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
ce50: 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
ce60: 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
ce70: 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  d..**.** An auth
ce80: 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
ce90: 68 65 6e 20 70 72 65 70 61 72 69 6e 67 20 53 51  hen preparing SQ
cea0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
ceb0: 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 0a 2a  m an untrusted.*
cec0: 2a 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  * source, to ens
ced0: 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
cee0: 20 73 74 61 74 65 6d 65 6e 74 73 20 64 6f 20 6e   statements do n
cef0: 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
cf00: 20 64 61 74 61 0a 2a 2a 20 74 68 61 74 20 74 68   data.** that th
cf10: 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
cf20: 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
cf30: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 74  at they do not t
cf40: 72 79 20 74 6f 0a 2a 2a 20 65 78 65 63 75 74 65  ry to.** execute
cf50: 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
cf60: 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
cf70: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
cf80: 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
cf90: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
cfa0: 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
cfb0: 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
cfc0: 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
cfd0: 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
cfe0: 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
cff0: 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
d000: 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
d010: 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
d020: 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
d030: 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
d040: 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
d050: 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
d060: 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
d070: 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
d080: 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
d090: 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
d0a0: 20 69 73 20 62 65 69 6e 67 20 70 72 65 70 61 72   is being prepar
d0b0: 65 64 20 74 68 61 74 20 64 69 73 61 6c 6c 6f 77  ed that disallow
d0c0: 73 20 65 76 65 72 79 74 68 69 6e 67 0a 2a 2a 20  s everything.** 
d0d0: 65 78 63 65 70 74 20 53 45 4c 45 43 54 20 73 74  except SELECT st
d0e0: 61 74 65 6d 65 6e 74 73 2e 20 20 0a 2a 2a 0a 2a  atements.  .**.*
d0f0: 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  * Only a single 
d100: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
d110: 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
d120: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d130: 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
d140: 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
d150: 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
d160: 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
d170: 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
d180: 20 63 61 6c 6c 2e 20 20 41 20 4e 55 4c 4c 20 61   call.  A NULL a
d190: 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20  uthorizer means 
d1a0: 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a  that no authoriz
d1b0: 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
d1c0: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 54  k is invoked.  T
d1d0: 68 65 20 64 65 66 61 75 6c 74 20 61 75 74 68 6f  he default autho
d1e0: 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a  rizer is NULL..*
d1f0: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
d200: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
d210: 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
d220: 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a  d only during .*
d230: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
d240: 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
d250: 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
d260: 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
d270: 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
d280: 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
d290: 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
d2a0: 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2f 0a 69 6e  3_step()]..*/.in
d2b0: 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
d2c0: 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
d2d0: 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
d2e0: 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
d2f0: 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
d300: 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
d310: 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
d320: 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
d330: 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
d340: 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
d350: 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
d360: 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
d370: 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
d380: 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
d390: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
d3a0: 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
d3b0: 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
d3c0: 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
d3d0: 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
d3e0: 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
d3f0: 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
d400: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
d410: 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
d420: 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
d430: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
d440: 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
d450: 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
d460: 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
d470: 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
d480: 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
d490: 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
d4a0: 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
d4b0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
d4c0: 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
d4d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
d4e0: 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
d4f0: 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
d500: 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
d510: 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
d520: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
d530: 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
d540: 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
d550: 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
d560: 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
d570: 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
d580: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
d590: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
d5a0: 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
d5b0: 69 7a 65 72 20 63 65 72 74 61 69 6e 20 53 51 4c  izer certain SQL
d5c0: 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
d5d0: 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
d5e0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
d5f0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
d600: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
d610: 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
d620: 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
d630: 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
d640: 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
d650: 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
d660: 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
d670: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
d680: 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
d690: 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
d6a0: 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
d6b0: 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
d6c0: 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
d6d0: 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a  ion is to be .**
d6e0: 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
d6f0: 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
d700: 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
d710: 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61  authorization ca
d720: 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
d730: 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
d740: 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
d750: 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
d760: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
d770: 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
d780: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
d790: 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 72  er.  The 5th par
d7a0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
d7b0: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
d7c0: 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
d7d0: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
d7e0: 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
d7f0: 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  , .** etc.) if a
d800: 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20  pplicable.  The 
d810: 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
d820: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
d830: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
d840: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
d850: 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
d860: 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
d870: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
d880: 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
d890: 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
d8a0: 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
d8b0: 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
d8c0: 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d  ly from .** top-
d8d0: 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
d8e0: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
d8f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
d910: 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
d920: 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
d930: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d940: 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
d950: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
d960: 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
d970: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
d980: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d990: 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
d9a0: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
d9b0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
d9c0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
d9d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d9e0: 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
d9f0: 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
da00: 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
da10: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
da20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
da30: 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
da40: 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
da50: 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
da60: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
da70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
da80: 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
da90: 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
daa0: 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
dab0: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
dac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
dad0: 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
dae0: 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
daf0: 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
db00: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
db10: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
db20: 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
db30: 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
db40: 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
db50: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
db60: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
db70: 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
db80: 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
db90: 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
dba0: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
dbb0: 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
dbc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
dbd0: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
dbe0: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
dbf0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
dc00: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
dc10: 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
dc20: 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
dc30: 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
dc40: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
dc50: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
dc60: 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
dc70: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
dc80: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
dc90: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
dca0: 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
dcb0: 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
dcc0: 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
dcd0: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
dce0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
dcf0: 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
dd00: 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
dd10: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
dd20: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
dd30: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
dd40: 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
dd50: 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
dd60: 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
dd70: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
dd80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dd90: 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
dda0: 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
ddb0: 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
ddc0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
ddd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dde0: 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
ddf0: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
de00: 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
de10: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
de20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
de30: 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
de40: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
de50: 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
de60: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
de70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
de80: 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
de90: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
dea0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
deb0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
dec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
ded0: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
dee0: 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
def0: 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
df00: 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
df10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
df20: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
df30: 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
df40: 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
df50: 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
df60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
df70: 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
df80: 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
df90: 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
dfa0: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
dfb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
dfc0: 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
dfd0: 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   22   /* NULL   
dfe0: 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
dff0: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
e000: 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
e010: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
e020: 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
e030: 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
e040: 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
e050: 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
e060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
e070: 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
e080: 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
e090: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
e0a0: 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
e0b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
e0c0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
e0d0: 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
e0e0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
e0f0: 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
e100: 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
e110: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
e120: 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
e130: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e140: 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
e150: 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
e160: 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
e170: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
e180: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
e190: 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
e1a0: 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
e1b0: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
e1c0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
e1d0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
e1e0: 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
e1f0: 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
e200: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
e210: 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
e220: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e230: 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
e240: 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
e250: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
e260: 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
e270: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e280: 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
e290: 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
e2a0: 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
e2b0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
e2c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e2d0: 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
e2e0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
e2f0: 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
e300: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e310: 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
e320: 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
e330: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
e340: 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
e350: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
e360: 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
e370: 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
e380: 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
e390: 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
e3a0: 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
e3b0: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
e3c0: 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
e3d0: 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
e3e0: 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
e3f0: 6b 65 64 0a 2a 2a 20 61 74 20 74 68 65 20 66 69  ked.** at the fi
e400: 72 73 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rst [sqlite3_ste
e410: 70 28 29 5d 20 66 6f 72 20 74 68 65 20 65 76 61  p()] for the eva
e420: 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 20 53 51  luation of an SQ
e430: 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
e440: 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
e450: 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
e460: 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
e470: 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
e480: 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
e490: 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
e4a0: 65 73 20 61 6e 64 20 69 6e 63 6c 75 64 65 73 0a  es and includes.
e4b0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6f  ** information o
e4c0: 6e 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  n how long that 
e4d0: 73 74 61 74 65 6d 65 6e 74 20 72 61 6e 2e 0a 2a  statement ran..*
e4e0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e4f0: 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69  _profile() API i
e500: 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
e510: 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
e520: 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75  tal and.** is su
e530: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e  bject to change.
e540: 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
e550: 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
e560: 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
e570: 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
e580: 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64  *), void*);.void
e590: 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
e5a0: 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
e5b0: 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
e5c0: 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
e5d0: 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
e5e0: 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
e5f0: 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
e600: 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
e610: 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  cks.**.** This r
e620: 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65  outine configure
e630: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
e640: 63 74 69 6f 6e 20 2d 20 74 68 65 20 70 72 6f 67  ction - the prog
e650: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20  ress callback - 
e660: 74 68 61 74 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  that.** is invok
e670: 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
e680: 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
e690: 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ing calls to [sq
e6a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 0a 2a  lite3_exec()],.*
e6b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
e6c0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
e6d0: 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41  get_table()].  A
e6e0: 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
e6f0: 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72  r this .** inter
e700: 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
e710: 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
e720: 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
e730: 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ry..**.** The pr
e740: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
e750: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  is invoked once 
e760: 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72 74  for every N virt
e770: 75 61 6c 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f  ual machine opco
e780: 64 65 73 2c 0a 2a 2a 20 77 68 65 72 65 20 4e 20  des,.** where N 
e790: 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
e7a0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66  gument to this f
e7b0: 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 70 72 6f  unction. The pro
e7c0: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a  gress callback.*
e7d0: 2a 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e  * itself is iden
e7e0: 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68  tified by the th
e7f0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
e800: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54  this function. T
e810: 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 61 72 67  he fourth.** arg
e820: 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75  ument to this fu
e830: 6e 63 74 69 6f 6e 20 69 73 20 61 20 76 6f 69 64  nction is a void
e840: 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
e850: 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  to the progress 
e860: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
e870: 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69  tion each time i
e880: 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  t is invoked..**
e890: 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  .** If a call to
e8a0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
e8b0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
e8c0: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
e8d0: 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a  _get_table()].**
e8e0: 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65   results in fewe
e8f0: 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73  r than N opcodes
e900: 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c   being executed,
e910: 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
e920: 73 73 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ss .** callback 
e930: 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64  is never invoked
e940: 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e 6c 79 20 61 20  ..** .** Only a 
e950: 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
e960: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
e970: 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
e980: 72 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  red for each.** 
e990: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  open database co
e9a0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 45 76 65 72 79  nnection.  Every
e9b0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e9c0: 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
e9d0: 72 28 29 0a 2a 2a 20 6f 76 65 72 77 72 69 74 65  r().** overwrite
e9e0: 73 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66  s the results of
e9f0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
ea00: 6c 6c 2e 0a 2a 2a 20 54 6f 20 72 65 6d 6f 76 65  ll..** To remove
ea10: 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
ea20: 6c 6c 62 61 63 6b 20 61 6c 74 6f 67 65 74 68 65  llback altogethe
ea30: 72 2c 20 70 61 73 73 20 4e 55 4c 4c 20 61 73 20  r, pass NULL as 
ea40: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
ea50: 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75  ument to this fu
ea60: 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
ea70: 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
ea80: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
ea90: 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68   result other th
eaa0: 61 6e 20 30 2c 20 74 68 65 6e 20 74 68 65 20 63  an 0, then the c
eab0: 75 72 72 65 6e 74 20 0a 2a 2a 20 71 75 65 72 79  urrent .** query
eac0: 20 69 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20   is immediately 
ead0: 74 65 72 6d 69 6e 61 74 65 64 20 61 6e 64 20 61  terminated and a
eae0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 68 61 6e  ny database chan
eaf0: 67 65 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  ges rolled back.
eb00: 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 61 69 6e 69  .** The containi
eb10: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
eb20: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
eb30: 65 70 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  ep()], or.** [sq
eb40: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
eb50: 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 20  )] call returns 
eb60: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
eb70: 2e 20 20 20 54 68 69 73 20 66 65 61 74 75 72 65  .   This feature
eb80: 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
eb90: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
eba0: 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 22   implement the "
ebb0: 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
ebc0: 6e 20 61 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20  n a.** progress 
ebd0: 64 69 61 6c 6f 67 20 62 6f 78 20 69 6e 20 61 20  dialog box in a 
ebe0: 47 55 49 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  GUI..*/.void sql
ebf0: 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
ec00: 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
ec10: 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
ec20: 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
ec30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
ec40: 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
ec50: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
ec60: 2a 0a 2a 2a 20 4f 70 65 6e 20 74 68 65 20 73 71  *.** Open the sq
ec70: 6c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  lite database fi
ec80: 6c 65 20 22 66 69 6c 65 6e 61 6d 65 22 2e 20 20  le "filename".  
ec90: 54 68 65 20 22 66 69 6c 65 6e 61 6d 65 22 20 69  The "filename" i
eca0: 73 20 55 54 46 2d 38 0a 2a 2a 20 65 6e 63 6f 64  s UTF-8.** encod
ecb0: 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ed for [sqlite3_
ecc0: 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  open()] and [sql
ecd0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
ece0: 61 6e 64 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  and UTF-16 encod
ecf0: 65 64 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ed.** in the nat
ed00: 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
ed10: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
ed20: 31 36 28 29 5d 2e 0a 2a 2a 20 41 6e 20 5b 73 71  16()]..** An [sq
ed30: 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 69  lite3*] handle i
ed40: 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  s returned in *p
ed50: 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20  pDb, even.** if 
ed60: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
ed70: 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
ed80: 20 69 73 20 6f 70 65 6e 65 64 20 28 6f 72 20 63   is opened (or c
ed90: 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
eda0: 75 6c 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53  ully,.** then [S
edb0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
edc0: 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65  urned. Otherwise
edd0: 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
ede0: 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 0a  s returned. The.
edf0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
ee00: 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
ee10: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 20 72  3_errmsg16()]  r
ee20: 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
ee30: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
ee40: 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
ee50: 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
ee60: 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a   of the error..*
ee70: 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
ee80: 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
ee90: 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
eea0: 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 5b  be UTF-8 if.** [
eeb0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
eec0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
eed0: 5f 76 32 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  _v2()] is called
eee0: 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
eef0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  f [sqlite3_open1
ef00: 36 28 29 5d 20 69 73 20 75 73 65 64 2e 0a 2a 2a  6()] is used..**
ef10: 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
ef20: 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
ef30: 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
ef40: 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 20  ened, resources 
ef50: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
ef60: 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  th the [sqlite3*
ef70: 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
ef80: 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 70  be released by p
ef90: 61 73 73 69 6e 67 20 69 74 20 74 6f 0a 2a 2a 20  assing it to.** 
efa0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
efb0: 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
efc0: 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
efd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
efe0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
eff0: 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
f000: 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ike [sqlite3_ope
f010: 6e 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  n()] except that
f020: 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 74 77 6f  .** provides two
f030: 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
f040: 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
f050: 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 20 6f 76  ional control ov
f060: 65 72 20 74 68 65 0a 2a 2a 20 6e 65 77 20 64 61  er the.** new da
f070: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f080: 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61  n.  The flags pa
f090: 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 6f  rameter can be o
f0a0: 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  ne of:.**.** <ol
f0b0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
f0c0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
f0d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
f0e0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
f0f0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  E].** <li>  [SQL
f100: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
f110: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
f120: 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f  EN_CREATE].** </
f130: 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ol>.**.** The fi
f140: 72 73 74 20 76 61 6c 75 65 20 6f 70 65 6e 73 20  rst value opens 
f150: 74 68 65 20 64 61 74 61 62 61 73 65 20 72 65 61  the database rea
f160: 64 2d 6f 6e 6c 79 2e 20 20 49 66 20 74 68 65 20  d-only.  If the 
f170: 64 61 74 61 62 61 73 65 20 64 6f 65 73 0a 2a 2a  database does.**
f180: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
f190: 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
f1a0: 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
f1b0: 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20  e second option 
f1c0: 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  opens.** the dat
f1d0: 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
f1e0: 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
f1f0: 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
f200: 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a  ading only if.**
f210: 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
f220: 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 2e  write protected.
f230: 20 20 49 6e 20 65 69 74 68 65 72 20 63 61 73 65    In either case
f240: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
f250: 73 74 20 61 6c 72 65 61 64 79 0a 2a 2a 20 65 78  st already.** ex
f260: 69 73 74 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  ist or an error 
f270: 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
f280: 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 20 6f  e third option o
f290: 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  pens the databas
f2a0: 65 0a 2a 2a 20 66 6f 72 20 72 65 61 64 69 6e 67  e.** for reading
f2b0: 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e 64   and writing and
f2c0: 20 63 72 65 61 74 65 73 20 69 74 20 69 66 20 69   creates it if i
f2d0: 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
f2e0: 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54 68 65  dy exist..** The
f2f0: 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73 20 69   third options i
f300: 73 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  s behavior that 
f310: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
f320: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
f330: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
f340: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
f350: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
f360: 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
f370: 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76  :", then an priv
f380: 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f 72 79  ate.** in-memory
f390: 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65   database is cre
f3a0: 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
f3b0: 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69  nection.  This i
f3c0: 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61 74 61  n-memory.** data
f3d0: 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
f3e0: 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
f3f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
f400: 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
f410: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  .** version of S
f420: 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61 6b 65  QLite might make
f430: 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
f440: 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
f450: 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62 65 67  ames.** that beg
f460: 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
f470: 63 68 61 72 61 63 74 65 72 2e 20 20 49 74 20 69  character.  It i
f480: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
f490: 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20 64 61  at .** when a da
f4a0: 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
f4b0: 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  really does begi
f4c0: 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20 74 68  n with.** ":" th
f4d0: 61 74 20 79 6f 75 20 70 72 65 66 69 78 20 74 68  at you prefix th
f4e0: 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
f4f0: 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b 65 20  a pathname like 
f500: 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f 69 64  "./" to.** avoid
f510: 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
f520: 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  * If the filenam
f530: 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
f540: 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
f550: 76 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a  vate temporary.*
f560: 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
f570: 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
f580: 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74  ed.  This privat
f590: 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
f5a0: 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
f5b0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
f5c0: 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
f5d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
f5e0: 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
f5f0: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
f600: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
f610: 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
f620: 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
f630: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
f640: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
f650: 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
f660: 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74 65 72  system .** inter
f670: 66 61 63 65 20 74 68 61 74 20 74 68 65 20 6e 65  face that the ne
f680: 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
f690: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
f6a0: 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  .  If the.** fou
f6b0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
f6c0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
f6d0: 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
f6e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a   [sqlite3_vfs].*
f6f0: 2a 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  * object is used
f700: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
f710: 74 6f 20 77 69 6e 64 6f 77 73 20 75 73 65 72 73  to windows users
f720: 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
f730: 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
f740: 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
f750: 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69 74 65  nt.** of [sqlite
f760: 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73  3_open()] and [s
f770: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
f780: 5d 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ] must be UTF-8,
f790: 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
f7a0: 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
f7b0: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
f7c0: 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
f7d0: 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
f7e0: 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
f7f0: 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
f800: 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
f810: 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
f820: 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  em into.** [sqli
f830: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b  te3_open()] or [
f840: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
f850: 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
f860: 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
f870: 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
f880: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
f890: 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
f8a0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
f8b0: 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
f8c0: 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
f8d0: 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
f8e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
f8f0: 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
f900: 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
f910: 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
f920: 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
f930: 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
f940: 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
f950: 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
f960: 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
f970: 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
f980: 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
f990: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
f9a0: 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
f9b0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
f9c0: 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
f9d0: 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
f9e0: 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
f9f0: 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
fa00: 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
fa10: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
fa20: 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
fa30: 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
fa40: 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
fa50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
fa60: 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
fa70: 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sages.**.** The 
fa80: 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
fa90: 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
faa0: 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a  rns the numeric.
fab0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
fac0: 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
fad0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
fae0: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
faf0: 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f  sult code].** fo
fb00: 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
fb10: 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
fb20: 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
fb30: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b  ciated.** with [
fb40: 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20  sqlite3] handle 
fb50: 27 64 62 27 2e 20 20 49 66 20 61 20 70 72 69 6f  'db'.  If a prio
fb60: 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
fb70: 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73  d but the.** mos
fb80: 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
fb90: 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
fba0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
fbb0: 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
fbc0: 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66  de().** is undef
fbd0: 69 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ined. .**.** The
fbe0: 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
fbf0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
fc00: 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
fc10: 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
fc20: 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
fc30: 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
fc40: 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
fc50: 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70 65  8 or UTF16 respe
fc60: 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
fc70: 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
fc80: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
fc90: 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
fca0: 6e 74 65 72 6e 61 6c 6c 79 2e 20 20 54 68 65 20  nternally.  The 
fcb0: 0a 2a 2a 20 73 74 72 69 6e 67 20 6d 61 79 20 62  .** string may b
fcc0: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
fcd0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 20   deallocated by 
fce0: 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
fcf0: 20 74 6f 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e   to SQLite.** in
fd00: 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
fd10: 73 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 73 20 74  s..**.** Calls t
fd20: 6f 20 6d 61 6e 79 20 73 71 6c 69 74 65 33 5f 2a  o many sqlite3_*
fd30: 20 66 75 6e 63 74 69 6f 6e 73 20 73 65 74 20 74   functions set t
fd40: 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  he error code an
fd50: 64 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  d string returne
fd60: 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
fd70: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71  _errcode()], [sq
fd80: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
fd90: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
fda0: 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 28 6f 76  rmsg16()].** (ov
fdb0: 65 72 77 72 69 74 69 6e 67 20 74 68 65 20 70 72  erwriting the pr
fdc0: 65 76 69 6f 75 73 20 76 61 6c 75 65 73 29 2e 20  evious values). 
fdd0: 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 73 20  Note that calls 
fde0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
fdf0: 6f 64 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ode()],.** [sqli
fe00: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61  te3_errmsg()], a
fe10: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
fe20: 73 67 31 36 28 29 5d 20 74 68 65 6d 73 65 6c 76  sg16()] themselv
fe30: 65 73 20 64 6f 20 6e 6f 74 20 61 66 66 65 63 74  es do not affect
fe40: 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 73 20   the.** results 
fe50: 6f 66 20 66 75 74 75 72 65 20 69 6e 76 6f 63 61  of future invoca
fe60: 74 69 6f 6e 73 2e 20 20 43 61 6c 6c 73 20 74 6f  tions.  Calls to
fe70: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68   API routines th
fe80: 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e  at do not return
fe90: 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64  .** an error cod
fea0: 65 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c  e (example: [sql
feb0: 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
fec0: 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 63 68  )]) do not.** ch
fed0: 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20 63  ange the error c
fee0: 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  ode returned by 
fef0: 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 49  this routine.  I
ff00: 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61  nterfaces that a
ff10: 72 65 0a 2a 2a 20 6e 6f 74 20 61 73 73 6f 63 69  re.** not associ
ff20: 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63  ated with a spec
ff30: 69 66 69 63 20 64 61 74 61 62 61 73 65 20 63 6f  ific database co
ff40: 6e 6e 65 63 74 69 6f 6e 20 28 65 78 61 6d 70 6c  nnection (exampl
ff50: 65 73 3a 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es:.** [sqlite3_
ff60: 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73  mprintf()] or [s
ff70: 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
ff80: 61 72 65 64 5f 63 61 63 68 65 28 29 5d 20 64 6f  ared_cache()] do
ff90: 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 74   not change.** t
ffa0: 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 20  he return code. 
ffb0: 20 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e 67   .**.** Assuming
ffc0: 20 6e 6f 20 6f 74 68 65 72 20 69 6e 74 65 72 76   no other interv
ffd0: 65 6e 69 6e 67 20 73 71 6c 69 74 65 33 5f 2a 20  ening sqlite3_* 
ffe0: 41 50 49 20 63 61 6c 6c 73 20 61 72 65 20 6d 61  API calls are ma
fff0: 64 65 2c 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  de, the error.**
10000 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62   code returned b
10010 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
10020 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
10030 74 68 20 74 68 65 20 73 61 6d 65 20 65 72 72 6f  th the same erro
10040 72 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  r as.** the stri
10050 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
10060 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
10070 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
10080 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a  errmsg16()]..*/.
10090 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
100a0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
100b0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
100c0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
100d0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
100e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
100f0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
10100 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10110 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
10120 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 49 6e 73 74  bject.**.** Inst
10130 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10140 65 63 74 20 72 65 70 72 65 73 65 6e 74 20 73 69  ect represent si
10150 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
10160 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a 20 69 73  nts.  This.** is
10170 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
10180 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
10190 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 20  statement" or a 
101a0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
101b0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
101c0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
101d0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20  tement"..** .** 
101e0 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
101f0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
10200 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
10210 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
10220 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
10230 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
10240 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
10250 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
10260 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
10270 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
10280 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
10290 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
102a0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b   using.**      [
102b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
102c0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
102d0 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d 2e 0a  _* interfaces]..
102e0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
102f0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
10300 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
10310 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
10320 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
10330 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
10340 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
10350 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
10360 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
10370 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
10380 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
10390 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
103a0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
103b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
103c0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
103d0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
103e0 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
103f0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
10400 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
10410 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
10420 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
10430 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
10440 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
10450 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
10460 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
10470 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
10480 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ment.**.** To ex
10490 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
104a0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
104b0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
104c0 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
104d0 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
104e0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
104f0 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  tines. .**.** Th
10500 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10510 20 22 64 62 22 20 69 73 20 61 6e 20 5b 73 71 6c   "db" is an [sql
10520 69 74 65 33 20 7c 20 53 51 4c 69 74 65 20 64 61  ite3 | SQLite da
10530 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d 20 0a  tabase handle] .
10540 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
10550 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
10560 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
10570 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
10580 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  _v2()].** or [sq
10590 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
105a0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
105b0 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69  rgument "zSql" i
105c0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
105d0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
105e0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
105f0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
10600 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
10610 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
10620 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
10630 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
10640 63 65 73 20 75 73 65 73 20 55 54 46 2d 38 20 61  ces uses UTF-8 a
10650 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
10660 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
10670 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
10680 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
10690 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42  .**.** If the nB
106a0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
106b0 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72  less.** than zer
106c0 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
106d0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66  read up to the f
106e0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
106f0 61 74 6f 72 2e 20 20 49 66 0a 2a 2a 20 6e 42 79  ator.  If.** nBy
10700 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
10710 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
10720 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
10730 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20 72  r of .** bytes r
10740 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
10750 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
10760 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
10770 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
10780 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
10790 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 63  e first '\000' c
107a0 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20  haracter or .** 
107b0 75 6e 74 69 6c 20 74 68 65 20 6e 42 79 74 65 2d  until the nByte-
107c0 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
107d0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
107e0 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73  **.** *pzTail is
107f0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
10800 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
10810 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
10820 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 53 51   the first.** SQ
10830 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
10840 53 71 6c 2e 20 20 54 68 69 73 20 72 6f 75 74 69  Sql.  This routi
10850 6e 65 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73  ne only compiles
10860 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
10870 6d 65 6e 74 0a 2a 2a 20 69 6e 20 7a 53 71 6c 2c  ment.** in zSql,
10880 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
10890 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
108a0 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
108b0 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a  ompiled..**.** *
108c0 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
108d0 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
108e0 70 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  piled .** [sqlit
108f0 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74  e3_stmt | SQL st
10900 61 74 65 6d 65 6e 74 20 73 74 72 75 63 74 75 72  atement structur
10910 65 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  e] that can be.*
10920 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
10930 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
10940 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72 65 20  ].  Or if there 
10950 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
10960 53 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a 20 73  Stmt may be.** s
10970 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20  et to NULL.  If 
10980 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
10990 6f 6e 74 61 69 6e 65 64 20 6e 6f 20 53 51 4c 20  ontained no SQL 
109a0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
109b0 20 61 6e 64 0a 2a 2a 20 65 6d 70 74 79 20 73 74   and.** empty st
109c0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
109d0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
109e0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20  is set to NULL. 
109f0 20 54 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   The calling.** 
10a00 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
10a10 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
10a20 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
10a30 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
10a40 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
10a50 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
10a60 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
10a70 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
10a80 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
10a90 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
10aa0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
10ab0 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49  ise an .** [SQLI
10ac0 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72  TE_ERROR | error
10ad0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
10ae0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
10af0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
10b00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
10b10 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
10b20 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
10b30 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
10b40 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
10b50 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
10b60 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
10b70 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
10b80 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
10b90 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
10ba0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
10bb0 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20  aged..** In the 
10bc0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
10bd0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
10be0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
10bf0 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
10c00 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
10c10 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
10c20 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a   a copy of the .
10c30 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
10c40 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
10c50 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
10c60 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
10c70 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20   to.** behave a 
10c80 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
10c90 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  wo ways:.**.** <
10ca0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49  ol>.** <li>.** I
10cb0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
10cc0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
10cd0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
10ce0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
10cf0 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
10d00 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
10d10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
10d20 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
10d30 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
10d40 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
10d50 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
10d60 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20  n it again.  If 
10d70 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
10d80 68 61 6e 67 65 64 20 69 6e 20 61 20 77 61 79 0a  hanged in a way.
10d90 2a 2a 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ** that makes th
10da0 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
10db0 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
10dc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
10dd0 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
10de0 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
10df0 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
10e00 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
10e10 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  ior, [SQLITE_SCH
10e20 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61  EMA] is.** now a
10e30 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
10e40 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
10e50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
10e60 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
10e70 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
10e80 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
10e90 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
10ea0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
10eb0 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 61  e text of the pa
10ec0 72 73 69 6e 67 0a 2a 2a 20 65 72 72 6f 72 20 74  rsing.** error t
10ed0 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
10ee0 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
10ef0 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c  ] return..** </l
10f00 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
10f10 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f   When an error o
10f20 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69  ccurs, .** [sqli
10f30 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
10f40 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
10f50 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20  he detailed .** 
10f60 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
10f70 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
10f80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
10f90 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
10fa0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
10fb0 73 75 63 68 20 61 73 20 64 69 72 65 63 74 6c 79  such as directly
10fc0 2e 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 79 20  ..** The legacy 
10fd0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
10fe0 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  t [sqlite3_step(
10ff0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
11000 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a  turn a generic.*
11010 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
11020 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6e 64   result code and
11030 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20   you would have 
11040 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
11050 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
11060 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e  ite3_reset()] in
11070 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
11080 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
11090 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
110a0 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  em..** With the 
110b0 22 76 32 22 20 70 72 65 70 61 72 65 20 69 6e 74  "v2" prepare int
110c0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
110d0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
110e0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 0a  or the error is.
110f0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  ** returned imme
11100 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
11110 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e  >.** </ol>.*/.in
11120 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
11130 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
11140 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
11150 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
11160 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
11170 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
11180 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
11190 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
111a0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
111b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
111c0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
111d0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
111e0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
111f0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
11200 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
11210 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
11220 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
11230 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
11240 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
11250 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
11260 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
11270 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
11280 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
11290 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
112a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
112b0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
112c0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
112d0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
112e0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
112f0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
11300 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
11310 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
11320 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
11330 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
11340 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
11350 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
11360 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
11370 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
11380 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
11390 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
113a0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
113b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
113c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
113d0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
113e0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
113f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
11400 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
11410 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
11420 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
11430 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
11440 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
11450 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
11460 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
11470 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
11480 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
11490 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
114a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
114b0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
114c0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
114d0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
114e0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
114f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
11500 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
11510 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
11520 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
11530 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
11540 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
11550 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
11560 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
11570 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
11580 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
11590 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
115a0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
115b0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
115c0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
115d0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
115e0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
115f0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
11600 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
11610 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
11620 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
11630 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
11640 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69 63 61  I3REF:  Dynamica
11650 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
11660 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 53 51 4c  Object.**.** SQL
11670 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
11680 20 74 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20   typing for the 
11690 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
116a0 2e 20 20 56 61 6c 75 65 73 20 63 61 6e 20 0a 2a  .  Values can .*
116b0 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  * be integers, f
116c0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
116d0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
116e0 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 20 20  LOBs, or NULL.  
116f0 57 68 65 6e 0a 2a 2a 20 70 61 73 73 69 6e 67 20  When.** passing 
11700 61 72 6f 75 6e 64 20 76 61 6c 75 65 73 20 69 6e  around values in
11710 74 65 72 6e 61 6c 6c 79 2c 20 65 61 63 68 20 76  ternally, each v
11720 61 6c 75 65 20 69 73 20 72 65 70 72 65 73 65 6e  alue is represen
11730 74 65 64 20 61 73 0a 2a 2a 20 61 6e 20 69 6e 73  ted as.** an ins
11740 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
11750 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
11760 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
11770 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
11780 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
11790 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75  API3REF:  SQL Fu
117a0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
117b0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
117c0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
117d0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
117e0 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
117f0 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
11800 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
11810 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20  ect.  A pointer 
11820 74 6f 20 73 75 63 68 20 61 6e 20 6f 62 6a 65 63  to such an objec
11830 74 20 69 73 20 74 68 65 0a 2a 2a 20 66 69 72 73  t is the.** firs
11840 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 75  t parameter to u
11850 73 65 72 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ser-defined SQL 
11860 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79  functions..*/.ty
11870 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
11880 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
11890 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
118a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
118b0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
118c0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
118d0 6d 65 6e 74 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  ments.**.** In t
118e0 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69  he SQL strings i
118f0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
11900 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
11910 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
11920 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
11930 6c 69 74 65 72 61 6c 73 20 63 61 6e 20 62 65 20  literals can be 
11940 72 65 70 6c 61 63 65 20 62 79 20 61 20 70 61 72  replace by a par
11950 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66  ameter in one of
11960 20 74 68 65 73 65 0a 2a 2a 20 66 6f 72 6d 73 3a   these.** forms:
11970 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
11980 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
11990 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 41  ?NNN.** <li>  :A
119a0 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41 41 41  AA.** <li>  @AAA
119b0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
119c0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
119d0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66   the parameter f
119e0 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  orms shown above
119f0 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67   NNN is an integ
11a00 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 41  er literal,.** A
11a10 41 41 20 69 73 20 61 6e 20 61 6c 70 68 61 6e 75  AA is an alphanu
11a20 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
11a30 20 61 6e 64 20 56 56 56 20 69 73 20 61 20 76 61   and VVV is a va
11a40 72 69 61 62 6c 65 20 6e 61 6d 65 20 61 63 63 6f  riable name acco
11a50 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  rding.** to the 
11a60 73 79 6e 74 61 78 20 72 75 6c 65 73 20 6f 66 20  syntax rules of 
11a70 74 68 65 20 54 43 4c 20 70 72 6f 67 72 61 6d 6d  the TCL programm
11a80 69 6e 67 20 6c 61 6e 67 75 61 67 65 2e 0a 2a 2a  ing language..**
11a90 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74   The values of t
11aa0 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20  hese parameters 
11ab0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
11ac0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
11ad0 65 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  es").** can be s
11ae0 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
11af0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
11b00 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
11b10 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ere..**.** The f
11b20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
11b30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
11b40 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
11b50 6c 77 61 79 73 20 69 73 20 61 20 70 6f 69 6e 74  lways is a point
11b60 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
11b70 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
11b80 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
11b90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
11ba0 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 69 74  e_v2()] or.** it
11bb0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 54 68 65  s variants.  The
11bc0 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
11bd0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
11be0 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
11bf0 72 20 74 6f 20 62 65 20 73 65 74 2e 20 20 54 68  r to be set.  Th
11c00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
11c10 72 20 68 61 73 0a 2a 2a 20 61 6e 20 69 6e 64 65  r has.** an inde
11c20 78 20 6f 66 20 31 2e 20 57 68 65 6e 20 74 68 65  x of 1. When the
11c30 20 73 61 6d 65 20 6e 61 6d 65 64 20 70 61 72 61   same named para
11c40 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
11c50 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
11c60 63 6f 6e 64 0a 2a 2a 20 61 6e 64 20 73 75 62 73  cond.** and subs
11c70 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
11c80 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
11c90 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
11ca0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
11cb0 65 2e 20 20 54 68 65 20 69 6e 64 65 78 20 66 6f  e.  The index fo
11cc0 72 0a 2a 2a 20 6e 61 6d 65 64 20 70 61 72 61 6d  r.** named param
11cd0 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
11ce0 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
11cf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
11d00 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
11d10 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
11d20 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 20 66  ed.  The index f
11d30 6f 72 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 70 61 72  or "?NNN".** par
11d40 61 6d 65 74 65 73 20 69 73 20 74 68 65 20 76 61  ametes is the va
11d50 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54  lue of NNN..** T
11d60 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
11d70 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
11d80 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  nd the compile-t
11d90 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ime.** parameter
11da0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
11db0 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66  ABLE_NUMBER (def
11dc0 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
11dd0 2e 0a 2a 2a 20 53 65 65 20 3c 61 20 68 72 65 66  ..** See <a href
11de0 3d 22 6c 69 6d 69 74 73 2e 68 74 6d 6c 22 3e 6c  ="limits.html">l
11df0 69 6d 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e 20 66  imits.html</a> f
11e00 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
11e10 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
11e20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
11e30 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
11e40 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
11e50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
11e60 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f 75   In those.** rou
11e70 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
11e80 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
11e90 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
11ea0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
11eb0 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70 61  tes.** in the pa
11ec0 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
11ed0 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
11ee0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
11ef0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 0a 2a  f bytes in the.*
11f00 2a 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  * string, not th
11f10 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
11f20 61 63 74 65 72 73 2e 20 20 54 68 65 20 6e 75 6d  acters.  The num
11f30 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
11f40 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
11f50 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
11f60 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 20  ator at the end 
11f70 6f 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49  of strings..** I
11f80 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
11f90 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
11fa0 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  ve, the length o
11fb0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
11fc0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
11fd0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
11fe0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
11ff0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  or..**.** The fi
12000 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
12010 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
12020 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
12030 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
12040 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
12050 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
12060 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
12070 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
12080 4f 42 20 6f 72 0a 2a 2a 20 74 65 78 74 20 61 66  OB or.** text af
12090 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
120a0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
120b0 20 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61    If the fifth a
120c0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
120d0 2a 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  * special value 
120e0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
120f0 20 74 68 65 6e 20 74 68 65 20 6c 69 62 72 61 72   then the librar
12100 79 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  y assumes that t
12110 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  he information.*
12120 2a 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  * is in static, 
12130 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
12140 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
12150 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 20 20  d to be freed.  
12160 49 66 20 74 68 65 0a 2a 2a 20 66 69 66 74 68 20  If the.** fifth 
12170 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
12180 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
12190 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 20  RANSIENT], then 
121a0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
121b0 0a 2a 2a 20 6f 77 6e 20 70 72 69 76 61 74 65 20  .** own private 
121c0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
121d0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
121e0 66 6f 72 65 20 74 68 65 20 73 71 6c 69 74 65 33  fore the sqlite3
121f0 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 72 6f 75  _bind_*().** rou
12200 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
12210 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12220 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
12230 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
12240 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 6e  BLOB of length n
12250 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
12260 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  ed with zeros.  
12270 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
12280 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
12290 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
122a0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
122b0 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68  hold it size) wh
122c0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
122d0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
122e0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
122f0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
12300 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66   place-holders f
12310 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
12320 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
12330 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
12340 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c   .** [sqlite3_bl
12350 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
12360 65 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  ent BLOB I/O] ro
12370 75 74 69 6e 65 73 2e 20 20 41 20 6e 65 67 61 74  utines.  A negat
12380 69 76 65 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72  ive.** value for
12390 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
123a0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
123b0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
123c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
123d0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
123e0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
123f0 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  after.** [sqlite
12400 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
12410 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74  (and its variant
12420 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  s) or [sqlite3_r
12430 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62  eset()] and.** b
12440 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
12450 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69  tep()]..** Bindi
12460 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
12470 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
12480 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
12490 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64  tine..** Unbound
124a0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
124b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
124c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ULL..**.** These
124d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
124e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
124f0 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72  success or an er
12500 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61  ror code if.** a
12510 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
12520 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e  ng.  [SQLITE_RAN
12530 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
12540 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
12550 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
12560 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c   of range.  [SQL
12570 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
12580 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
12590 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49   fails..** [SQLI
125a0 54 45 5f 4d 49 53 55 53 45 5d 20 69 73 20 72 65  TE_MISUSE] is re
125b0 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20  turned if these 
125c0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
125d0 6c 65 64 20 6f 6e 20 61 20 76 69 72 74 75 61 6c  led on a virtual
125e0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 74 68 61 74  .** machine that
125f0 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74   is the wrong st
12600 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73  ate or which has
12610 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69   already been fi
12620 6e 61 6c 69 7a 65 64 2e 0a 2a 2f 0a 69 6e 74 20  nalized..*/.int 
12630 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
12640 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
12650 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
12660 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
12670 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
12680 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
12690 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
126a0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
126b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
126c0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
126d0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
126e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
126f0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
12700 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
12710 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
12720 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
12730 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
12740 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
12750 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
12760 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
12770 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
12780 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
12790 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
127a0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
127b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
127c0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
127d0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
127e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
127f0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
12800 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
12810 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
12820 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
12830 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
12840 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
12850 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
12860 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
12870 65 72 20 4f 66 20 48 6f 73 74 20 50 61 72 61 6d  er Of Host Param
12880 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 52 65 74 75  eters.**.** Retu
12890 72 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 68  rn the largest h
128a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 6e  ost parameter in
128b0 64 65 78 20 69 6e 20 74 68 65 20 70 72 65 63 6f  dex in the preco
128c0 6d 70 69 6c 65 64 20 73 74 61 74 65 6d 65 6e 74  mpiled statement
128d0 20 67 69 76 65 6e 0a 2a 2a 20 61 73 20 74 68 65   given.** as the
128e0 20 61 72 67 75 6d 65 6e 74 2e 20 20 57 68 65 6e   argument.  When
128f0 20 74 68 65 20 68 6f 73 74 20 70 61 72 61 6d 65   the host parame
12900 74 65 72 73 20 61 72 65 20 6f 66 20 74 68 65 20  ters are of the 
12910 66 6f 72 6d 73 20 6c 69 6b 65 20 22 3a 41 41 41  forms like ":AAA
12920 22 0a 2a 2a 20 6f 72 20 22 3f 22 2c 20 74 68 65  ".** or "?", the
12930 6e 20 74 68 65 79 20 61 72 65 20 61 73 73 69 67  n they are assig
12940 6e 65 64 20 73 65 71 75 65 6e 74 69 61 6c 20 69  ned sequential i
12950 6e 63 72 65 61 73 69 6e 67 20 6e 75 6d 62 65 72  ncreasing number
12960 73 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 77  s beginning.** w
12970 69 74 68 20 6f 6e 65 2c 20 73 6f 20 74 68 65 20  ith one, so the 
12980 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
12990 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
129a0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 48 6f 77  parameters.  How
129b0 65 76 65 72 0a 2a 2a 20 69 66 20 74 68 65 20 73  ever.** if the s
129c0 61 6d 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74  ame host paramet
129d0 65 72 20 6e 61 6d 65 20 69 73 20 75 73 65 64 20  er name is used 
129e0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 2c 20  multiple times, 
129f0 65 61 63 68 20 6f 63 63 75 72 72 61 6e 63 65 0a  each occurrance.
12a00 2a 2a 20 69 73 20 67 69 76 65 6e 20 74 68 65 20  ** is given the 
12a10 73 61 6d 65 20 6e 75 6d 62 65 72 2c 20 73 6f 20  same number, so 
12a20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
12a30 65 64 20 69 6e 20 74 68 61 74 20 63 61 73 65 20  ed in that case 
12a40 69 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  is the number.**
12a50 20 6f 66 20 75 6e 69 71 75 65 20 68 6f 73 74 20   of unique host 
12a60 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 2e  parameter names.
12a70 20 20 49 66 20 68 6f 73 74 20 70 61 72 61 6d 65    If host parame
12a80 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
12a90 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 61 72 65 20 75   "?NNN".** are u
12aa0 73 65 64 20 28 77 68 65 72 65 20 4e 4e 4e 20 69  sed (where NNN i
12ab0 73 20 61 6e 20 69 6e 74 65 67 65 72 29 20 74 68  s an integer) th
12ac0 65 6e 20 74 68 65 72 65 20 6d 69 67 68 74 20 62  en there might b
12ad0 65 20 67 61 70 73 20 69 6e 20 74 68 65 0a 2a 2a  e gaps in the.**
12ae0 20 6e 75 6d 62 65 72 69 6e 67 20 61 6e 64 20 74   numbering and t
12af0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
12b00 64 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  d by this interf
12b10 61 63 65 20 69 73 20 74 68 65 20 69 6e 64 65 78  ace is the index
12b20 20 6f 66 20 74 68 65 0a 2a 2a 20 68 6f 73 74 20   of the.** host 
12b30 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 74  parameter with t
12b40 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78  he largest index
12b50 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   value..**.** Th
12b60 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
12b70 6d 65 6e 74 20 6d 75 73 74 20 6e 6f 74 20 62 65  ment must not be
12b80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
12b90 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 0a  ze | finalized].
12ba0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 69 73  ** prior to this
12bb0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 6e   routine returnn
12bc0 69 6e 67 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ing.  Otherwise 
12bd0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
12be0 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 61 6e 64  undefined.** and
12bf0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
12c00 72 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  rable..*/.int sq
12c10 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
12c20 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
12c30 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
12c40 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
12c50 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
12c60 65 74 65 72 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eter.**.** This 
12c70 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
12c80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
12c90 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74   name of the n-t
12ca0 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 61  h parameter in a
12cb0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
12cc0 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
12cd0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 48 6f 73  atement]..** Hos
12ce0 74 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  t parameters of 
12cf0 74 68 65 20 66 6f 72 6d 20 22 3a 41 41 41 22 20  the form ":AAA" 
12d00 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 56  or "@AAA" or "$V
12d10 56 56 22 20 68 61 76 65 20 61 20 6e 61 6d 65 0a  VV" have a name.
12d20 2a 2a 20 77 68 69 63 68 20 69 73 20 74 68 65 20  ** which is the 
12d30 73 74 72 69 6e 67 20 22 3a 41 41 41 22 20 6f 72  string ":AAA" or
12d40 20 22 40 41 41 41 22 20 6f 72 20 22 24 56 56 56   "@AAA" or "$VVV
12d50 22 2e 20 20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ".  .** In other
12d60 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
12d70 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
12d80 72 20 22 40 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "@".** is incl
12d90 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
12da0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72  the name..** Par
12db0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
12dc0 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e  orm "?" or "?NNN
12dd0 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a  " have no name..
12de0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
12df0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20  bound parameter 
12e00 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
12e10 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
12e20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69  If the value n i
12e30 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
12e40 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61  r if the n-th pa
12e50 72 61 6d 65 74 65 72 20 69 73 20 6e 61 6d 65 6c  rameter is namel
12e60 65 73 73 2c 0a 2a 2a 20 74 68 65 6e 20 4e 55 4c  ess,.** then NUL
12e70 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
12e80 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
12e90 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 69 6e  ing is always in
12ea0 20 74 68 65 0a 2a 2a 20 55 54 46 2d 38 20 65 6e   the.** UTF-8 en
12eb0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
12ec0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
12ed0 65 72 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c  er was originall
12ee0 79 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 61  y specified.** a
12ef0 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
12f00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
12f10 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
12f20 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
12f30 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
12f40 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
12f50 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
12f60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
12f70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12f80 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
12f90 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
12fa0 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69  n Name.**.** Thi
12fb0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
12fc0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  s the index of a
12fd0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
12fe0 77 69 74 68 20 74 68 65 20 67 69 76 65 6e 20 6e  with the given n
12ff0 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ame..** The name
13000 20 6d 75 73 74 20 6d 61 74 63 68 20 65 78 61 63   must match exac
13010 74 6c 79 2e 20 20 49 66 20 6e 6f 20 70 61 72 61  tly.  If no para
13020 6d 65 74 65 72 20 77 69 74 68 20 74 68 65 20 67  meter with the g
13030 69 76 65 6e 20 6e 61 6d 65 20 69 73 20 0a 2a 2a  iven name is .**
13040 20 66 6f 75 6e 64 2c 20 72 65 74 75 72 6e 20 30   found, return 0
13050 2e 20 20 50 61 72 61 6d 65 74 65 72 20 6e 61 6d  .  Parameter nam
13060 65 73 20 6d 75 73 74 20 62 65 20 55 54 46 38 2e  es must be UTF8.
13070 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
13080 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
13090 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
130a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
130b0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
130c0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
130d0 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
130e0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
130f0 65 6e 74 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  ent.**.** Contra
13100 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
13110 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
13120 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
13130 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74  oes not.** reset
13140 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
13150 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
13160 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 73 71  gs] on a .** [sq
13170 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
13180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
13190 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  .  Use this rout
131a0 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20  ine to.** reset 
131b0 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
131c0 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
131d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
131e0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
131f0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
13200 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
13210 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
13220 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
13230 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e  .** Return the n
13240 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
13250 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
13260 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
13270 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
13280 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20  stmt | compiled 
13290 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  SQL statement]. 
132a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
132b0 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74  urns 0.** if pSt
132c0 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61  mt is an SQL sta
132d0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
132e0 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
132f0 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c   (for .** exampl
13300 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2f  e an UPDATE)..*/
13310 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
13320 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
13330 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
13340 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13350 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
13360 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
13370 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
13380 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
13390 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
133a0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
133b0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
133c0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
133d0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ECT statement.  
133e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
133f0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
13400 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
13410 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54   pointer to a UT
13420 46 38 20 73 74 72 69 6e 67 20 61 6e 64 20 73 71  F8 string and sq
13430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
13440 65 31 36 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  e16().** returns
13450 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
13460 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54  UTF16 string.  T
13470 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
13480 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 73 71  er is the.** [sq
13490 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
134a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
134b0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
134c0 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74   the SELECT stat
134d0 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65  ement..** The se
134e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
134f0 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d  s the column num
13500 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d  ber.  The left-m
13510 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a  ost column is.**
13520 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
13530 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
13540 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
13550 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
13560 65 72 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  er the .** [sqli
13570 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61  te3_stmt | prepa
13580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
13590 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
135a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
135b0 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  ()].** or until 
135c0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71  the next call sq
135d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
135e0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
135f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a  olumn_name16().*
13600 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  * on the same co
13610 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73  lumn..**.** If s
13620 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
13630 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
13640 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
13650 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
13660 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
13670 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
13680 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
13690 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
136a0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
136b0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 63  s returned..*/.c
136c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
136d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
136e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
136f0 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
13700 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
13710 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
13720 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
13730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13740 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
13750 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
13760 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
13770 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
13780 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
13790 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f  ne what column o
137a0 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20  f what.** table 
137b0 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73  in which databas
137c0 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20  e a result of a 
137d0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
137e0 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20   comes from..** 
137f0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
13800 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
13810 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
13820 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
13830 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 38 20  * either a UTF8 
13840 6f 72 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e  or UTF16 string.
13850 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f    The _database_
13860 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
13870 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
13880 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
13890 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
138a0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
138b0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
138c0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
138d0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
138e0 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65   name..** The re
138f0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
13900 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20   valid until.** 
13910 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
13920 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
13930 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
13940 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  oyed using.** [s
13950 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
13960 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
13970 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
13980 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
13990 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
139a0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
139b0 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20  **.** The names 
139c0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
139d0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
139e0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
139f0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
13a00 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
13a10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
13a20 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
13a30 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c  e following call
13a40 73 20 69 73 20 61 20 0a 2a 2a 20 5b 73 71 6c 69  s is a .** [sqli
13a50 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69  te3_stmt | compi
13a60 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
13a70 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  t]..** These fun
13a80 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
13a90 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
13aa0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
13ab0 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74  eturned by .** t
13ac0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
13ad0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
13ae0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
13af0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ument..**.** If 
13b00 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
13b10 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
13b20 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
13b30 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20  xpression.** or 
13b40 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
13b50 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
13b60 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
13b70 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a  these functions.
13b80 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20  ** return NULL. 
13b90 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
13ba0 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e  return the .** n
13bb0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
13bc0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
13bd0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  ble and column t
13be0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
13bf0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  .** column was e
13c00 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
13c10 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c  *.** As with all
13c20 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
13c30 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69  Is, those postfi
13c40 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65  xed with "16" re
13c50 74 75 72 6e 20 55 54 46 2d 31 36 0a 2a 2a 20 65  turn UTF-16.** e
13c60 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20  ncoded strings, 
13c70 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
13c80 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
13c90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50  ..**.** These AP
13ca0 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
13cb0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
13cc0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
13cd0 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
13ce0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
13cf0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65  UMN_METADATA pre
13d00 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
13d10 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
13d20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
13d30 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
13d40 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
13d50 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
13d60 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
13d70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
13d80 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
13d90 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
13da0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
13db0 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
13dc0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
13dd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
13de0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
13df0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
13e00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
13e10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
13e20 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
13e30 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
13e40 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
13e50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
13e60 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
13e70 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
13e80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
13e90 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
13ea0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
13eb0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
13ec0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
13ed0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
13ee0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
13ef0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
13f00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
13f10 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
13f20 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
13f30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
13f40 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
13f50 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
13f60 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  t.**.** The firs
13f70 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
13f80 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
13f90 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74   compiled SQL st
13fa0 61 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66  atement]. .** If
13fb0 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
13fc0 69 73 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  is a SELECT stat
13fd0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
13fe0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
13ff0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
14000 75 6c 74 20 73 65 74 20 20 6f 66 20 74 68 61 74  ult set  of that
14010 20 53 45 4c 45 43 54 20 69 73 20 61 20 74 61 62   SELECT is a tab
14020 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
14030 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
14040 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
14050 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
14060 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
14070 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
14080 74 75 72 6e 65 64 2e 20 49 66 20 74 68 65 20 4e  turned. If the N
14090 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
140a0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
140b0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
140c0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
140d0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
140e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
140f0 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
14100 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
14110 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 46 6f  TF-8 encoded. Fo
14120 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 0a 2a 2a  r example, in.**
14130 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
14140 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
14150 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
14160 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41  ARIANT);.**.** A
14170 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
14180 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
14190 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
141a0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
141b0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e  M t1;.**.** Then
141c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
141d0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
141e0 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
141f0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  for the second.*
14200 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  * result column 
14210 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
14220 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
14230 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
14240 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29  column.** (i==0)
14250 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ..**.** SQLite u
14260 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
14270 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f  time typing.  So
14280 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
14290 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
142a0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
142b0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
142c0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
142d0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
142e0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
142f0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
14300 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
14310 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
14320 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
14330 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
14340 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
14350 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73  tic.  Type.** is
14360 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
14370 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
14380 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
14390 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
143a0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
143b0 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
143c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
143d0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
143e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2c  (sqlite3_stmt *,
143f0 20 69 6e 74 20 69 29 3b 0a 63 6f 6e 73 74 20 76   int i);.const v
14400 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
14410 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
14420 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
14430 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33  );../* .** CAPI3
14440 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65 20 41  REF:  Evaluate A
14450 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
14460 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e 20 5b  **.** After an [
14470 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53  sqlite3_stmt | S
14480 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  QL statement] ha
14490 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
144a0 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74  with a call.** t
144b0 6f 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  o either [sqlite
144c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
144d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
144e0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
144f0 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  o one of.** the 
14500 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
14510 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
14520 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
14530 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a  3_prepare16()],.
14540 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 66 75 6e  ** then this fun
14550 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 63 61  ction must be ca
14560 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
14570 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
14580 74 65 20 74 68 65 20 0a 2a 2a 20 73 74 61 74 65  te the .** state
14590 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
145a0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
145b0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
145c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
145d0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
145e0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
145f0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
14600 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
14610 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
14620 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
14630 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
14640 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
14650 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
14660 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
14670 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
14680 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14690 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
146a0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
146b0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
146c0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
146d0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
146e0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
146f0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
14700 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
14710 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
14720 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
14730 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ed..**.** In the
14740 20 6c 61 67 61 63 79 20 69 6e 74 65 72 66 61 63   lagacy interfac
14750 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
14760 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
14770 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
14780 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  , .** [SQLITE_DO
14790 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
147a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
147b0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
147c0 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  SUSE]..** With t
147d0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
147e0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
147f0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  her [SQLITE_OK |
14800 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a   result code].**
14810 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
14820 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
14830 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d  d result code] m
14840 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
14850 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a   as.** well..**.
14860 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
14870 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
14880 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
14890 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
148a0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
148b0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
148c0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
148d0 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  ob.  If the stat
148e0 65 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49  ement is a COMMI
148f0 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  T.** or occurs o
14900 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
14910 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
14920 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
14930 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
14940 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
14950 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
14960 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63   a COMMIT and oc
14970 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a  curs within a.**
14980 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
14990 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
149a0 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
149b0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
149c0 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
149d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ing..**.** [SQLI
149e0 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
149f0 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
14a00 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
14a10 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
14a20 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
14a30 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
14a40 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
14a50 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
14a60 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
14a70 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
14a80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
14a90 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
14aa0 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
14ab0 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
14ac0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
14ad0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
14ae0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
14af0 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
14b00 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
14b10 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  hen .** [SQLITE_
14b20 52 4f 57 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROW] is returned
14b30 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
14b40 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
14b50 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f  ready.** for pro
14b60 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 20 63  cessing by the c
14b70 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
14b80 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
14b90 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  d using.** the [
14ba0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
14bb0 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65  nt | column acce
14bc0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
14bd0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
14be0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
14bf0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
14c00 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
14c10 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54  a..** .** [SQLIT
14c20 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
14c30 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
14c40 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
14c50 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
14c60 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
14c70 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
14c80 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
14c90 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
14ca0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
14cb0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
14cc0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
14cd0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
14ce0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
14cf0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
14d00 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
14d10 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
14d20 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a   code (example:.
14d30 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
14d40 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
14d50 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
14d60 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
14d70 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
14d80 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
14d90 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
14da0 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
14db0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
14dc0 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
14dd0 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
14de0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
14df0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
14e00 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
14e10 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
14e20 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
14e30 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
14e40 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
14e50 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
14e60 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
14e70 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
14e80 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
14e90 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
14ea0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
14eb0 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
14ec0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
14ed0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
14ee0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
14ef0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
14f00 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
14f10 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  d .** previously
14f20 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
14f30 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
14f40 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
14f50 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
14f60 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
14f70 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
14f80 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
14f90 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
14fa0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
14fb0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
14fc0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
14fd0 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
14fe0 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
14ff0 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63  .** In the legac
15000 79 20 69 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a  y interface, .**
15010 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
15020 70 28 29 20 41 50 49 20 61 6c 77 61 79 73 20 72  p() API always r
15030 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
15040 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20   error code,.** 
15050 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
15060 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72  following any er
15070 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
15080 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
15090 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
150a0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
150b0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  all [sqlite3_res
150c0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
150d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
150e0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
150f0 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70 65  d one of the spe
15100 63 69 66 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45  cific.** [SQLITE
15110 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20  _ERROR | result 
15120 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
15130 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
15140 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
15150 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
15160 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
15170 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
15180 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
15190 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
151a0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
151b0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
151c0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
151d0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
151e0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
151f0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
15200 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
15210 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
15220 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
15230 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15240 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
15250 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
15260 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65  hen the .** more
15270 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49 54   specific [SQLIT
15280 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74  E_ERROR | result
15290 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
152a0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
152b0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
152c0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
152d0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
152e0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
152f0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
15300 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
15310 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
15320 50 49 33 52 45 46 3a 0a 2a 2a 0a 2a 2a 20 52 65  PI3REF:.**.** Re
15330 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
15340 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  of values in the
15350 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
15360 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  the result set..
15370 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 63 61  **.** After a ca
15380 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
15390 74 65 70 28 29 5d 20 74 68 61 74 20 72 65 74 75  tep()] that retu
153a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  rns [SQLITE_ROW]
153b0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  , this routine.*
153c0 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  * will return th
153d0 65 20 73 61 6d 65 20 76 61 6c 75 65 20 61 73 20  e same value as 
153e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
153f0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 20 66 75 6e  umn_count()] fun
15400 63 74 69 6f 6e 2e 0a 2a 2a 20 41 66 74 65 72 20  ction..** After 
15410 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
15420 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e   has returned an
15430 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
15440 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f  [SQLITE_BUSY], o
15450 72 0a 2a 2a 20 61 20 5b 53 51 4c 49 54 45 5f 45  r.** a [SQLITE_E
15460 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64  RROR | error cod
15470 65 5d 2c 20 6f 72 20 62 65 66 6f 72 65 20 5b 73  e], or before [s
15480 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
15490 61 73 20 62 65 65 6e 20 0a 2a 2a 20 63 61 6c 6c  as been .** call
154a0 65 64 20 6f 6e 20 74 68 65 20 5b 73 71 6c 69 74  ed on the [sqlit
154b0 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
154c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f  ed statement] fo
154d0 72 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  r the first time
154e0 2c 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  ,.** this routin
154f0 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  e returns zero..
15500 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
15510 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
15520 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
15530 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15540 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
15550 61 74 79 70 65 73 0a 2a 2a 0a 2a 2a 20 45 76 65  atypes.**.** Eve
15560 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
15570 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
15580 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
15590 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
155a0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
155b0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
155c0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
155d0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
155e0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
155f0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
15600 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
15610 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   NULL.** </ul>.*
15620 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
15630 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
15640 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
15650 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
15660 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
15670 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
15680 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
15690 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
156a0 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
156b0 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
156c0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
156d0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
156e0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
156f0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
15700 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
15710 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
15720 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f 74  SQLITE3_TEXT not
15730 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
15740 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
15750 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
15760 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
15770 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
15780 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
15790 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
157a0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
157b0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
157c0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
157d0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
157e0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
157f0 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
15800 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
15810 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
15820 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20 56  I3REF: Results V
15830 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
15840 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ry.**.** These r
15850 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
15860 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
15870 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  .** a single col
15880 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
15890 6e 74 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  nt result row of
158a0 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76   a query.  In ev
158b0 65 72 79 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  ery.** case the 
158c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
158d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
158e0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
158f0 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61 74 65  stmt | SQL state
15900 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
15910 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64  ing.** evaluated
15920 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
15930 74 6d 74 2a 5d 20 74 68 61 74 20 77 61 73 20 72  tmt*] that was r
15940 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  eturned from .**
15950 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15960 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
15970 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  f its variants) 
15980 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  and.** the secon
15990 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
159a0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
159b0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
159c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20  information .** 
159d0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
159e0 65 64 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f  ed.  The left-mo
159f0 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
15a00 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68   result set.** h
15a10 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30  as an index of 0
15a20 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
15a30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
15a40 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
15a50 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
15a60 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
15a70 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65   the column inde
15a80 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
15a90 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
15aa0 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20   undefined. .** 
15ab0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
15ac0 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
15ad0 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
15ae0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
15af0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
15b00 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
15b10 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
15b20 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
15b30 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
15b40 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
15b50 69 7a 65 28 29 5d 20 68 61 73 20 62 65 65 6e 20  ize()] has been 
15b60 63 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 6c  call subsequentl
15b70 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
15b80 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
15b90 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
15ba0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
15bb0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
15bc0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
15bd0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
15be0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
15bf0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
15c00 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
15c10 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
15c20 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
15c30 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
15c40 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
15c50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
15c60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
15c70 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
15c80 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
15c90 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
15ca0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
15cb0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
15cc0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
15cd0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
15ce0 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a  undefined.  .**.
15cf0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
15d00 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
15d10 74 69 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tine returns .**
15d20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
15d30 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
15d40 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
15d50 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
15d60 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
15d70 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e  umn.  The return
15d80 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
15d90 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
15da0 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
15db0 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
15dc0 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
15dd0 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
15de0 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
15df0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
15e00 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
15e10 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
15e20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
15e30 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
15e40 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
15e50 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
15e60 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
15e70 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
15e80 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
15e90 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
15ea0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
15eb0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
15ec0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
15ed0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
15ee0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
15ef0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
15f00 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
15f10 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
15f20 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
15f30 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
15f40 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
15f50 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
15f60 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
15f70 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72  mn_bytes() .** r
15f80 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
15f90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
15fa0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
15fb0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66  or string..** If
15fc0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
15fd0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
15fe0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
15ff0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
16000 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
16010 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
16020 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
16030 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
16040 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
16050 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
16060 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
16070 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
16080 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
16090 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
160a0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
160b0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
160c0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
160d0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
160e0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
160f0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65  t string..** The
16100 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
16110 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
16120 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
16130 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a  ator at the end.
16140 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
16150 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20  .  For clarity: 
16160 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
16170 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ed is the number
16180 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
16190 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
161a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
161b0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
161c0 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
161d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
161e0 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
161f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
16200 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 7a  t16(),.** even z
16210 65 72 6f 2d 6c 65 6e 67 74 68 20 73 74 72 69 6e  ero-length strin
16220 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
16230 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
16240 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76   The return.** v
16250 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
16260 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
16270 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
16280 68 20 62 6c 6f 62 20 69 73 20 61 6e 20 61 72 62  h blob is an arb
16290 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65  itrary.** pointe
162a0 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e  r, possibly even
162b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
162c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
162d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
162e0 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  6() routine is s
162f0 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65  imilar to sqlite
16300 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
16310 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74  .** but leaves t
16320 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46  he result in UTF
16330 2d 31 36 20 69 6e 73 74 65 61 64 20 6f 66 20 55  -16 instead of U
16340 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a  TF-8.  .** The z
16350 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
16360 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
16370 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a  n this count..**
16380 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
16390 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
163a0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
163b0 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
163c0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
163d0 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
163e0 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
163f0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
16400 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
16410 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
16420 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
16430 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
16440 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65  rnally to do the
16450 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61   conversion.** a
16460 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
16470 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
16480 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
16490 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68 61 74 0a  onversions that.
164a0 2a 2a 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  ** are applied:.
164b0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
164c0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
164d0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
164e0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
164f0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
16500 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
16510 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
16520 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
16530 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
16540 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
16550 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
16560 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
16570 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
16580 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
16590 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
165a0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
165b0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
165c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
165d0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
165e0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
165f0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
16600 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
16610 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
16620 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
16630 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
16640 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
16650 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
16660 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
16670 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
16680 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
16690 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
166a0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
166b0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
166c0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72  <td> Same as for
166d0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
166e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
166f0 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
16700 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
16710 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
16720 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
16730 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
16740 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
16750 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
16760 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
16770 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
16780 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
16790 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
167a0 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
167b0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
167c0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
167d0 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
167e0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
167f0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
16800 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
16810 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
16820 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
16830 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
16840 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
16850 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
16860 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
16870 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
16880 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
16890 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
168a0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
168b0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
168c0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
168d0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
168e0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
168f0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
16900 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
16910 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
16920 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
16930 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
16940 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
16950 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
16960 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
16970 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
16980 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
16990 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
169a0 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
169b0 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
169c0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
169d0 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e  .** on equavalen
169e0 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
169f0 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
16a00 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
16a10 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
16a20 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
16a30 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
16a40 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
16a50 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
16a60 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
16a70 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
16a80 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
16a90 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
16aa0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
16ab0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
16ac0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
16ad0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
16ae0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
16af0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
16b00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
16b10 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
16b20 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20  dated. .** Type 
16b30 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
16b40 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
16b50 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
16b60 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
16b70 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
16b80 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c  ** <ul>.** <li><
16b90 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20  p>  The initial 
16ba0 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
16bb0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
16bc0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20  lumn_text() .** 
16bd0 20 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c 69           or sqli
16be0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
16bf0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
16c00 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
16c10 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
16c20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
16c30 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
16c40 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a  ng.</p></li>.**.
16c50 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20  ** <li><p>  The 
16c60 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
16c70 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
16c80 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
16c90 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
16ca0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
16cb0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
16cc0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
16cd0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
16ce0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
16cf0 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31          to UTF-1
16d00 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  6.</p></li>.**.*
16d10 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69  * <li><p>  The i
16d20 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
16d30 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
16d40 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
16d50 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
16d60 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
16d70 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
16d80 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
16d90 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
16da0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
16db0 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70      to UTF-8.</p
16dc0 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ></li>.** </ul>.
16dd0 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e  **.** Conversion
16de0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
16df0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
16e00 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
16e10 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
16e20 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
16e30 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
16e40 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
16e50 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
16e60 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
16e70 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
16e80 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74  pointer points t
16e90 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  o will have been
16ea0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
16eb0 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
16ec0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
16ed0 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
16ee0 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
16ef0 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 20  but sometime it 
16f00 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
16f10 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
16f20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
16f30 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
16f40 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  ated.  .**.** Th
16f50 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
16f60 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
16f70 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
16f80 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
16f90 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
16fa0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
16fb0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e  ays:.**.**  <ul>
16fc0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
16fd0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
16fe0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
16ff0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
17000 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
17010 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
17020 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
17030 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
17040 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
17050 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
17060 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
17070 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
17080 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
17090 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e  )</li>.**  </ul>
170a0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
170b0 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
170c0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
170d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71  olumn_text(), sq
170e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
170f0 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  b(),.** or sqlit
17100 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
17110 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
17120 65 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  e the result int
17130 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a 2a  o the desired.**
17140 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
17150 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
17160 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 73  umn_bytes() or s
17170 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
17180 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69  tes16() to.** fi
17190 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
171a0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
171b0 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73  ot mix call to s
171c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
171d0 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  xt() or.** sqlit
171e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
171f0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
17200 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
17210 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64 6f  tes16().  And do
17220 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c   not.** mix call
17230 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
17240 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69 74  umn_text16() wit
17250 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
17260 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
17270 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  )..**.** The poi
17280 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
17290 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
172a0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
172b0 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
172c0 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
172d0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
172e0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
172f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
17300 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
17310 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
17320 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  ed.  The memory 
17330 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
17340 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
17350 64 20 62 6c 6f 62 73 20 69 73 20 66 72 65 65 64  d blobs is freed
17360 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
17370 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
17380 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
17390 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
173a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
173b0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
173c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
173d0 74 63 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71  tc. into .** [sq
173e0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
173f0 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79  *.** If a memory
17400 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
17410 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
17420 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
17430 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
17440 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
17450 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
17460 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
17470 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
17480 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
17490 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
174a0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
174b0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
174c0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
174d0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
174e0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
174f0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
17500 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
17510 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  EM]..*/.const vo
17520 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
17530 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
17540 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
17550 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
17560 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
17570 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
17580 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
17590 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
175a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
175b0 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
175c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
175d0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
175e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
175f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
17600 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
17610 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
17620 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
17630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
17640 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
17650 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
17660 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
17670 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
17680 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
17690 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
176a0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
176b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
176c0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
176d0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
176e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
176f0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
17700 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
17710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
17720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
17730 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
17740 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
17750 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
17760 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
17770 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
17780 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
17790 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
177a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
177b0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a  ed to delete a .
177c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
177d0 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20   | compiled SQL 
177e0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74  statement]. If t
177f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
17800 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73 75 63  .** executed suc
17810 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f  cessfully, or no
17820 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c  t executed at al
17830 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f  l, then SQLITE_O
17840 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  K is returned..*
17850 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f  * If execution o
17860 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
17870 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a  failed then an .
17880 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
17890 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f   | error code] o
178a0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
178b0 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
178c0 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69  error code].** i
178d0 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a  s returned. .**.
178e0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
178f0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
17900 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
17910 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
17920 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
17930 65 33 5f 73 74 6d 74 20 7c 20 76 69 72 74 75 61  e3_stmt | virtua
17940 6c 20 6d 61 63 68 69 6e 65 5d 2e 20 20 49 66 20  l machine].  If 
17950 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
17960 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  ine has not .** 
17970 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
17980 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f  ion when this ro
17990 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c  utine is called,
179a0 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a   that is like.**
179b0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e   encountering an
179c0 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74   error or an int
179d0 65 72 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73  errupt.  (See [s
179e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
179f0 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70  ()].) .** Incomp
17a00 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79  lete updates may
17a10 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
17a20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  and transactions
17a30 20 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a   cancelled,  .**
17a40 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
17a50 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
17a60 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 53 51   and the .** [SQ
17a70 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73  LITE_ERROR | res
17a80 75 6c 74 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ult code] return
17a90 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
17aa0 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e  TE_ABORT]..*/.in
17ab0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
17ac0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
17ad0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
17ae0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
17af0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
17b00 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
17b10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
17b20 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
17b30 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
17b40 74 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t a .** [sqlite3
17b50 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
17b60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20   SQL statement] 
17b70 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20  object..** back 
17b80 74 6f 20 69 74 27 73 20 69 6e 69 74 69 61 6c 20  to it's initial 
17b90 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
17ba0 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
17bb0 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65  ** Any SQL state
17bc0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
17bd0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
17be0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
17bf0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
17c00 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
17c10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
17c20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
17c30 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
17c40 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
17c50 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
17c60 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
17c70 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
17c80 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
17c90 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
17ca0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
17cb0 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
17cc0 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
17cd0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
17ce0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
17cf0 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
17d00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
17d10 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a  or aggregates.**
17d20 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
17d30 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
17d40 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
17d50 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
17d60 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69  ates.  The.** di
17d70 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65  fference only be
17d80 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73  tween the two is
17d90 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
17da0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a   parameter, the.
17db0 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  ** name of the (
17dc0 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
17dd0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 69   or aggregate, i
17de0 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
17df0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
17e00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
17e10 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20 66  n() and UTF-16 f
17e20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
17e30 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
17e40 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
17e50 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
17e60 5b 73 71 6c 69 74 65 33 20 7c 20 64 61 74 61 62  [sqlite3 | datab
17e70 61 73 65 20 68 61 6e 64 6c 65 5d 20 74 68 61 74  ase handle] that
17e80 20 68 6f 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51   holds the.** SQ
17e90 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
17ea0 67 72 65 67 61 74 65 20 69 73 20 74 6f 20 62 65  gregate is to be
17eb0 20 61 64 64 65 64 20 6f 72 20 72 65 64 65 66 69   added or redefi
17ec0 6e 65 64 2e 20 49 66 20 61 20 73 69 6e 67 6c 65  ned. If a single
17ed0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
17ee0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
17ef0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69  atabase handle i
17f00 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20  nternally, then 
17f10 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  SQL.** functions
17f20 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6d   or aggregates m
17f30 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64  ust be added ind
17f40 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63  ividually to eac
17f50 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61  h database.** ha
17f60 6e 64 6c 65 20 77 69 74 68 20 77 68 69 63 68 20  ndle with which 
17f70 74 68 65 79 20 77 69 6c 6c 20 62 65 20 75 73 65  they will be use
17f80 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
17f90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17fa0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
17fb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
17fc0 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f   be created.** o
17fd0 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  r redefined..** 
17fe0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
17ff0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
18000 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
18010 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
18020 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   .** zero-termin
18030 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
18040 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
18050 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
18060 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
18070 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65  cters.  Any atte
18080 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
18090 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
180a0 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
180b0 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  ill result in an
180c0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72   SQLITE_ERROR er
180d0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ror..**.** The t
180e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
180f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
18100 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
18110 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
18120 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
18130 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70  takes. If this p
18140 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
18150 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53  tive, then the S
18160 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
18170 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
18180 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
18190 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  of arguments..**
181a0 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
181b0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
181c0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
181d0 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  at .** [SQLITE_U
181e0 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
181f0 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
18200 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
18210 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
18220 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
18230 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
18240 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
18250 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
18260 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
18270 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
18280 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
18290 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
182a0 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
182b0 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
182c0 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
182d0 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20  an another.  It 
182e0 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a  is allowed to.**
182f0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
18300 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
18310 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
18320 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
18330 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
18340 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
18350 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
18360 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
18370 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
18380 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  .** When multipl
18390 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
183a0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
183b0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
183c0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
183d0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
183e0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
183f0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
18400 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
18410 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
18420 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
18430 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
18440 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
18450 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78  care what.** tex
18460 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  t encoding is us
18470 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
18480 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
18490 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54  uld be.** [SQLIT
184a0 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  E_ANY]..**.** Th
184b0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
184c0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
184d0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
184e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
184f0 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * of the functio
18500 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
18510 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
18520 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  r using.** [sqli
18530 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
18540 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65  ..**.** The seve
18550 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20  nth, eighth and 
18560 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73  ninth parameters
18570 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
18580 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
18590 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
185a0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
185b0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
185c0 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  t the SQL.** fun
185d0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
185e0 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c  te. A scalar SQL
185f0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
18600 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
18610 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78  tion of.** the x
18620 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  Func callback on
18630 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly, NULL pointer
18640 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  s should be pass
18650 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 0a  ed as the xStep.
18660 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61  ** and xFinal pa
18670 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67  rameters. An agg
18680 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
18690 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
186a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
186b0 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78  * of xStep and x
186c0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73  Final and NULL s
186d0 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
186e0 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65  for xFunc. To de
186f0 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74  lete an.** exist
18700 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
18710 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
18720 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c  ass NULL for all
18730 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
18740 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ** callback..**.
18750 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74  ** It is permitt
18760 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
18770 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
18780 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
18790 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
187a0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
187b0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
187c0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
187d0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
187e0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
187f0 6e 67 20 70 65 72 66 65 72 72 65 64 20 74 65 78  ng perferred tex
18800 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51  t encodings.  SQ
18810 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
18820 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
18830 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  ion most closely
18840 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
18850 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
18860 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
18870 20 75 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71   used..*/.int sq
18880 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
18890 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
188a0 20 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   *,.  const char
188b0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
188c0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
188d0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
188e0 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78  oid*,.  void (*x
188f0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
18900 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
18910 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
18920 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
18930 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
18940 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
18950 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
18960 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
18970 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
18980 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
18990 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
189a0 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e3*,.  const voi
189b0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
189c0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
189d0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
189e0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a  void*,.  void (*
189f0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
18a00 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
18a10 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
18a20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
18a30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
18a40 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
18a50 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
18a60 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
18a70 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
18a80 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
18a90 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
18aa0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
18ab0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
18ac0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
18ad0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
18ae0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
18af0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
18b00 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
18b10 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
18b20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
18b30 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
18b40 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
18b50 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
18b60 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
18b70 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
18b80 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
18b90 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
18ba0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
18bb0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
18bc0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
18bd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
18be0 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
18bf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
18c00 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
18c10 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
18c20 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
18c30 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
18c40 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20  I3REF: Obsolete 
18c50 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
18c60 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
18c70 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f  are all now obso
18c80 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20  lete.  In order 
18c90 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
18ca0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
18cb0 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
18cc0 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69  r code, we conti
18cd0 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a  nue to support.*
18ce0 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
18cf0 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  s.  However, new
18d00 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f   development pro
18d10 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f  jects should avo
18d20 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
18d30 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
18d40 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
18d50 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
18d60 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
18d70 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
18d80 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
18d90 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74  to tell you want
18da0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74   they do..*/.int
18db0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
18dc0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
18dd0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20  _context*);.int 
18de0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
18df0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
18e00 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
18e10 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
18e20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
18e30 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
18e40 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
18e50 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76  recover(void);.v
18e60 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
18e70 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
18e80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  ;.int sqlite3_me
18e90 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
18ea0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
18eb0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
18ec0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
18ed0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18ee0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
18ef0 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
18f00 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
18f10 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
18f20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
18f30 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
18f40 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
18f50 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
18f60 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
18f70 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
18f80 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
18f90 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
18fa0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
18fb0 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
18fc0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
18fd0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
18fe0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
18ff0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
19000 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
19010 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
19020 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
19030 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
19040 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
19050 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
19060 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
19070 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
19080 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
19090 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
190a0 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
190b0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
190c0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
190d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
190e0 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
190f0 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
19100 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
19110 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
19120 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
19130 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
19140 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
19150 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
19160 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
19170 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
19180 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
19190 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
191a0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
191b0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
191c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
191d0 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  umn_blob | sqlit
191e0 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74  e3_column_* rout
191f0 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74 68 61  ines] except tha
19200 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  t .** these rout
19210 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
19220 6c 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  le [sqlite3_valu
19230 65 2a 5d 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  e*] pointer inst
19240 65 61 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ead.** of an [sq
19250 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
19260 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
19270 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
19280 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
19290 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
192a0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
192b0 74 72 61 63 74 73 20 61 20 55 54 46 31 36 20 73  tracts a UTF16 s
192c0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
192d0 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
192e0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
192f0 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73  chine.  The.** s
19300 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
19310 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
19320 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
19330 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
19340 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 31 36  ** extract UTF16
19350 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
19360 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
19370 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
19380 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ively..**.** The
19390 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
193a0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
193b0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
193c0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
193d0 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
193e0 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
193f0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
19400 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
19410 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
19420 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
19430 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
19440 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
19450 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
19460 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
19470 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
19480 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 72  formation (in or
19490 64 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20  der.** words if 
194a0 74 68 65 20 76 61 6c 75 65 20 69 73 20 6f 72 69  the value is ori
194b0 67 69 6e 61 6c 20 61 20 73 74 72 69 6e 67 20 74  ginal a string t
194c0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
194d0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
194e0 20 69 74 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74   it is done.  Ot
194f0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
19500 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54  rsion occurs.  T
19510 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  he .** [SQLITE_I
19520 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
19530 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
19540 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
19550 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
19560 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
19570 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
19580 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
19590 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72  ter that.** is r
195a0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
195b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
195c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
195d0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
195e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
195f0 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
19600 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
19610 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
19620 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
19630 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
19640 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
19650 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
19660 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
19670 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
19680 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
19690 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  6()].  .**.** Th
196a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
196b0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
196c0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
196d0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
196e0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
196f0 70 6c 69 65 64 20 74 68 65 20 73 71 6c 69 74 65  plied the sqlite
19700 33 5f 76 61 6c 75 65 2a 20 70 61 72 61 6d 65 74  3_value* paramet
19710 65 72 73 2e 0a 2a 2a 20 4f 72 2c 20 69 66 20 74  ers..** Or, if t
19720 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
19730 2a 20 61 72 67 75 6d 65 6e 74 20 63 6f 6d 65 73  * argument comes
19740 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
19750 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
19760 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2c  )].** interface,
19770 20 74 68 65 6e 20 74 68 65 73 65 20 72 6f 75 74   then these rout
19780 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 20 63  ines should be c
19790 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
197a0 61 6d 65 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ame thread.** th
197b0 61 74 20 72 61 6e 20 5b 73 71 6c 69 74 65 33 5f  at ran [sqlite3_
197c0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 2e  column_value()].
197d0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
197e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
197f0 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
19800 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
19810 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
19820 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
19830 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
19840 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
19850 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
19860 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
19870 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
19880 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
19890 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
198a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
198b0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
198c0 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
198d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
198e0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
198f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
19900 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
19910 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
19920 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
19930 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
19940 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
19950 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
19960 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
19970 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
19980 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
19990 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
199a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
199b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
199c0 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
199d0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
199e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
199f0 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
19a00 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
19a10 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
19a20 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
19a30 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a  tion Context.**.
19a40 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
19a50 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61  ation of aggrega
19a60 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
19a70 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   use this routin
19a80 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a  e to allocate.**
19a90 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72   a structure for
19aa0 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
19ab0 74 61 74 65 2e 20 20 54 68 65 20 66 69 72 73 74  tate.  The first
19ac0 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
19ad0 6e 65 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20  ne.** is called 
19ae0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
19af0 20 61 67 67 72 65 67 61 74 65 2c 20 61 20 6e 65   aggregate, a ne
19b00 77 20 73 74 72 75 63 74 75 72 65 20 6f 66 20 73  w structure of s
19b10 69 7a 65 20 6e 42 79 74 65 73 0a 2a 2a 20 69 73  ize nBytes.** is
19b20 20 61 6c 6c 6f 63 61 74 65 64 2c 20 7a 65 72 6f   allocated, zero
19b30 65 64 2c 20 61 6e 64 20 72 65 74 75 72 6e 65 64  ed, and returned
19b40 2e 20 20 4f 6e 20 73 75 62 73 65 71 75 65 6e 74  .  On subsequent
19b50 20 63 61 6c 6c 73 20 28 66 6f 72 20 74 68 65 0a   calls (for the.
19b60 2a 2a 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  ** same aggregat
19b70 65 20 69 6e 73 74 61 6e 63 65 29 20 74 68 65 20  e instance) the 
19b80 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
19b90 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 69 6d  eturned.  The im
19ba0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
19bb0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
19bc0 20 63 61 6e 20 75 73 65 20 74 68 65 20 72 65 74   can use the ret
19bd0 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20  urned buffer to 
19be0 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e  accumulate data.
19bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 66 66 65  .**.** The buffe
19c00 72 20 61 6c 6c 6f 63 61 74 65 64 20 69 73 20 66  r allocated is f
19c10 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
19c20 6c 79 20 62 79 20 53 51 4c 69 74 65 20 77 68 61  ly by SQLite wha
19c30 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  n the aggregate.
19c40 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  ** query conclud
19c50 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
19c60 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68  rst parameter sh
19c70 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f  ould be a copy o
19c80 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  f the .** [sqlit
19c90 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
19ca0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
19cb0 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
19cc0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
19cd0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
19ce0 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
19cf0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
19d00 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
19d10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
19d20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
19d30 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
19d40 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
19d50 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
19d60 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
19d70 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
19d80 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
19d90 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
19da0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
19db0 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
19dc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19dd0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
19de0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
19df0 54 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  The pUserData pa
19e00 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
19e10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
19e20 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
19e30 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
19e40 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
19e50 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64  routines.** used
19e60 20 74 6f 20 72 65 67 69 73 74 65 72 20 75 73 65   to register use
19e70 72 20 66 75 6e 63 74 69 6f 6e 73 20 69 73 20 61  r functions is a
19e80 76 61 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a 20 74  vailable to.** t
19e90 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
19ea0 6e 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  n of the functio
19eb0 6e 20 75 73 69 6e 67 20 74 68 69 73 20 63 61 6c  n using this cal
19ec0 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  l..**.** This ro
19ed0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
19ee0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
19ef0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
19f00 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
19f10 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
19f20 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
19f30 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
19f40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
19f50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19f60 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
19f70 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
19f80 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
19f90 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
19fa0 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
19fb0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
19fc0 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
19fd0 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68 20 61  meta-data with a
19fe0 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
19ff0 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
1a000 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
1a010 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
1a020 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
1a030 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
1a040 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
1a050 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
1a060 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
1a070 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
1a080 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d 61 79  ed meta-data may
1a090 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
1a0a0 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
1a0b0 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
1a0c0 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
1a0d0 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
1a0e0 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
1a0f0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
1a100 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
1a110 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
1a120 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
1a130 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61  ed as.** meta-da
1a140 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
1a150 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
1a160 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
1a170 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
1a180 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
1a190 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
1a1a0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
1a1b0 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
1a1c0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
1a1d0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
1a1e0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
1a1f0 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
1a200 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
1a210 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
1a220 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
1a230 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
1a240 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
1a250 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
1a260 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
1a270 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1a280 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 2d 64  er to the meta-d
1a290 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
1a2a0 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  d with the Nth a
1a2b0 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 20 74 6f  rgument value to
1a2c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 53 51 4c   the current SQL
1a2d0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
1a2e0 6c 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  l, where N is th
1a2f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a300 65 72 2e 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64  er. If no meta-d
1a310 61 74 61 20 68 61 73 20 62 65 65 6e 20 73 65 74  ata has been set
1a320 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 76 61 6c   for.** that val
1a330 75 65 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ue, then a NULL 
1a340 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
1a350 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
1a360 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
1a370 74 61 28 29 20 69 73 20 75 73 65 64 20 74 6f 20  ta() is used to 
1a380 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64  associate meta-d
1a390 61 74 61 20 77 69 74 68 20 61 6e 20 53 51 4c 0a  ata with an SQL.
1a3a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  ** function argu
1a3b0 6d 65 6e 74 2e 20 54 68 65 20 74 68 69 72 64 20  ment. The third 
1a3c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
1a3d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
1a3e0 74 61 2d 64 61 74 61 0a 2a 2a 20 74 6f 20 62 65  ta-data.** to be
1a3f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1a400 20 74 68 65 20 4e 74 68 20 75 73 65 72 20 66 75   the Nth user fu
1a410 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 20  nction argument 
1a420 76 61 6c 75 65 2e 20 54 68 65 20 66 6f 75 72 74  value. The fourt
1a430 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73  h.** parameter s
1a440 70 65 63 69 66 69 65 73 20 61 20 64 65 73 74 72  pecifies a destr
1a450 75 63 74 6f 72 20 74 68 61 74 20 77 69 6c 6c 20  uctor that will 
1a460 62 65 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  be called on the
1a470 20 6d 65 74 61 2d 0a 2a 2a 20 64 61 74 61 20 70   meta-.** data p
1a480 6f 69 6e 74 65 72 20 74 6f 20 72 65 6c 65 61 73  ointer to releas
1a490 65 20 69 74 20 77 68 65 6e 20 69 74 20 69 73 20  e it when it is 
1a4a0 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
1a4b0 65 64 2e 20 49 66 20 74 68 65 20 0a 2a 2a 20 64  ed. If the .** d
1a4c0 65 73 74 72 75 63 74 6f 72 20 69 73 20 4e 55 4c  estructor is NUL
1a4d0 4c 2c 20 69 74 20 69 73 20 6e 6f 74 20 69 6e 76  L, it is not inv
1a4e0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70  oked..**.** In p
1a4f0 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61  ractice, meta-da
1a500 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
1a510 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
1a520 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
1a530 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
1a540 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
1a550 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
1a560 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
1a570 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
1a580 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a   SQL variables..
1a590 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1a5a0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
1a5b0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
1a5c0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
1a5d0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
1a5e0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
1a5f0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1a600 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
1a610 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1a620 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
1a630 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
1a640 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1a650 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 76 6f  , int, void*, vo
1a660 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
1a670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a680 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
1a690 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
1a6a0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
1a6b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
1a6c0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 66   special value f
1a6d0 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
1a6e0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
1a6f0 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
1a700 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
1a710 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
1a720 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
1a730 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64  ob()].  If the d
1a740 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
1a750 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
1a760 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
1a770 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
1a780 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
1a790 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
1a7a0 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
1a7b0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
1a7c0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
1a7d0 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49  d.  The .** SQLI
1a7e0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
1a7f0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
1a800 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
1a810 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
1a820 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
1a830 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
1a840 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
1a850 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
1a860 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
1a870 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
1a880 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
1a890 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
1a8a0 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
1a8b0 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
1a8c0 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
1a8d0 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
1a8e0 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
1a8f0 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
1a900 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
1a910 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
1a920 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
1a930 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
1a940 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
1a950 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
1a960 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
1a970 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
1a980 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
1a990 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
1a9a0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
1a9b0 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
1a9c0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
1a9d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1a9e0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
1a9f0 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
1aa00 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
1aa10 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
1aa20 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
1aa30 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
1aa40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1aa50 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
1aa60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1aa70 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
1aa80 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
1aa90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1aaa0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
1aab0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
1aac0 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a 20  ch like the .** 
1aad0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1aae0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
1aaf0 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20 66  d_*] family of f
1ab00 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a 2a  unctions used.**
1ab10 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
1ab20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
1ab30 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
1ab40 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
1ab50 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73  fer to the.** [s
1ab60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1ab70 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
1ab80 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  * documentation]
1ab90 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
1aba0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
1abb0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1abc0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
1abd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
1abe0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
1abf0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
1ac00 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
1ac10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
1ac20 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
1ac30 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 70 61 72  ion.  The.** par
1ac40 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1ac50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
1ac60 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
1ac70 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
1ac80 69 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  is the text of a
1ac90 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
1aca0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1acb0 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
1acc0 28 29 20 63 61 75 73 65 20 74 68 65 20 66 75 6e  () cause the fun
1acd0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
1ace0 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 72 6f 77  tion.** to throw
1acf0 20 61 6e 64 20 65 72 72 6f 72 20 69 6e 64 69 63   and error indic
1ad00 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
1ad10 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
1ad20 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70  o long.** to rep
1ad30 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  resent..**.** Th
1ad40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
1ad50 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
1ad60 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
1ad70 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
1ad80 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
1ad90 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1ada0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
1adb0 65 78 74 5d 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  ext] pointer..*/
1adc0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1add0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
1ade0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
1adf0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
1ae00 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
1ae10 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1ae20 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
1ae30 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
1ae40 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
1ae50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
1ae60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1ae70 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
1ae80 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
1ae90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
1aea0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1aeb0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1aec0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
1aed0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
1aee0 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
1aef0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
1af00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
1af10 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
1af20 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
1af30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1af40 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
1af50 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
1af60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1af70 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
1af80 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
1af90 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
1afa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
1afb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1afc0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
1afd0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
1afe0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
1aff0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
1b000 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1b010 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1b020 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
1b030 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
1b040 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
1b050 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1b060 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1b070 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
1b080 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b090 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1b0a0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
1b0b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1b0c0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
1b0d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1b0e0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1b0f0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
1b100 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1b110 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
1b120 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1b130 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
1b140 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1b150 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
1b160 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1b170 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
1b180 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
1b190 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
1b1a0 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68  quences.**.** Th
1b1b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
1b1c0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
1b1d0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
1b1e0 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
1b1f0 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c  [sqlite3*] handl
1b200 65 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  e specified as t
1b210 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1b220 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  t. .**.** The na
1b230 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f  me of the new co
1b240 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1b250 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73   is specified as
1b260 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
1b270 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
1b280 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
1b290 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
1b2a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
1b2b0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
1b2c0 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73  -16 string for s
1b2d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1b2e0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 20 49 6e  llation16().  In
1b2f0 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68   all cases.** th
1b300 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64  e name is passed
1b310 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   as the second f
1b320 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
1b330 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
1b340 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  d argument may b
1b350 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
1b360 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55  stants [SQLITE_U
1b370 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  TF8],.** [SQLITE
1b380 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51  _UTF16LE] or [SQ
1b390 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69  LITE_UTF16BE], i
1b3a0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
1b3b0 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64  he user-supplied
1b3c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65  .** routine expe
1b3d0 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64  cts to be passed
1b3e0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
1b3f0 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69  ings encoded usi
1b400 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46  ng UTF-8,.** UTF
1b410 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
1b420 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d  n or UTF-16 big-
1b430 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
1b440 65 6c 79 2e 20 20 54 68 65 0a 2a 2a 20 74 68 69  ely.  The.** thi
1b450 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68  rd argument migh
1b460 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54  t also be [SQLIT
1b470 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
1b480 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
1b490 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65  t.** the routine
1b4a0 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72   expects pointer
1b4b0 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64  s to 16-bit word
1b4c0 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73   aligned strings
1b4d0 0a 2a 2a 20 6f 66 20 55 54 46 31 36 20 69 6e 20  .** of UTF16 in 
1b4e0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1b4f0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
1b500 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a  t computer..**.*
1b510 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
1b520 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
1b530 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
1b540 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
1b550 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
1b560 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c  . If it is NULL,
1b570 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d   this is the sam
1b580 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68  e as deleting th
1b590 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
1b5a0 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74  equence (so that
1b5b0 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63   SQLite cannot c
1b5c0 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e  all it anymore).
1b5d0 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 75   Each time the u
1b5e0 73 65 72 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ser.** supplied 
1b5f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
1b600 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65  ked, it is passe
1b610 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
1b620 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a  void* passed as.
1b630 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  ** the fourth ar
1b640 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1b650 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1b660 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  on() or.** sqlit
1b670 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1b680 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66  ion16() as its f
1b690 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
1b6a0 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  **.** The remain
1b6b0 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
1b6c0 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69   the user-suppli
1b6d0 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74  ed routine are t
1b6e0 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65  wo strings,.** e
1b6f0 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20  ach represented 
1b700 62 79 20 61 20 5b 6c 65 6e 67 74 68 2c 20 64 61  by a [length, da
1b710 74 61 5d 20 70 61 69 72 20 61 6e 64 20 65 6e 63  ta] pair and enc
1b720 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f  oded in the enco
1b730 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73  ding.** that was
1b740 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
1b750 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68  hird argument wh
1b760 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
1b770 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a   sequence was.**
1b780 20 72 65 67 69 73 74 65 72 65 64 2e 20 54 68 65   registered. The
1b790 20 75 73 65 72 20 72 6f 75 74 69 6e 65 20 73 68   user routine sh
1b7a0 6f 75 6c 64 20 72 65 74 75 72 6e 20 6e 65 67 61  ould return nega
1b7b0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
1b7c0 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68 65  sitive if.** the
1b7d0 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
1b7e0 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
1b7f0 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
1b800 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
1b810 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e  .** string. i.e.
1b820 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49   (STRING1 - STRI
1b830 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NG2)..**.** The 
1b840 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1b850 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
1b860 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
1b870 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1b880 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68  n().** excapt th
1b890 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65  at it takes an e
1b8a0 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68  xtra argument wh
1b8b0 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63  ich is a destruc
1b8c0 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63  tor for.** the c
1b8d0 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  ollation.  The d
1b8e0 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
1b8f0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  led when the col
1b900 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73  lation is.** des
1b910 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61  troyed and is pa
1b920 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74  ssed a copy of t
1b930 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1b940 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  ter void* pointe
1b950 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  r.** of the sqli
1b960 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1b970 74 69 6f 6e 5f 76 32 28 29 2e 20 20 43 6f 6c 6c  tion_v2().  Coll
1b980 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72  ations are destr
1b990 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65  oyed when.** the
1b9a0 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
1b9b0 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20   by later calls 
1b9c0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
1b9d0 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
1b9e0 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ons.** or when t
1b9f0 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61  he [sqlite3*] da
1ba00 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73  tabase handle is
1ba10 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
1ba20 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
1ba30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1ba40 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1ba50 69 6f 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ion_v2() interfa
1ba60 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ce is experiment
1ba70 61 6c 20 61 6e 64 0a 2a 2a 20 73 75 62 6a 65 63  al and.** subjec
1ba80 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
1ba90 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20  uture releases. 
1baa0 20 54 68 65 20 6f 74 68 65 72 20 63 6f 6c 6c 61   The other colla
1bab0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 0a 2a 2a  tion creation.**
1bac0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 73   functions are s
1bad0 74 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  table..*/.int sq
1bae0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1baf0 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
1bb00 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
1bb10 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
1bb20 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
1bb30 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
1bb40 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
1bb50 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
1bb60 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
1bb70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
1bb80 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
1bb90 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
1bba0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
1bbb0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
1bbc0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
1bbd0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
1bbe0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
1bbf0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
1bc00 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
1bc10 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
1bc20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1bc30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
1bc40 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
1bc50 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
1bc60 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
1bc70 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
1bc80 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
1bc90 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1bca0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
1bcb0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
1bcc0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
1bcd0 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
1bce0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20  lbacks.**.** To 
1bcf0 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
1bd00 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
1bd10 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
1bd20 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
1bd30 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
1bd40 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
1bd50 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
1bd60 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
1bd70 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61  with the.** data
1bd80 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62  base handle to b
1bd90 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65  e called wheneve
1bda0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
1bdb0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
1bdc0 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64  e is.** required
1bdd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
1bde0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
1bdf0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
1be00 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
1be10 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
1be20 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
1be30 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
1be40 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
1be50 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
1be60 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
1be70 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
1be80 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
1be90 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
1bea0 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d  is used, the nam
1beb0 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64  es.** are passed
1bec0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
1bed0 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
1bee0 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20  e order. A call 
1bef0 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e  to either.** fun
1bf00 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
1bf10 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
1bf20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
1bf30 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1bf40 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
1bf50 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
1bf60 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
1bf70 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
1bf80 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1bf90 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1bfa0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
1bfb0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
1bfc0 65 64 65 64 31 36 28 29 2e 20 54 68 65 20 73 65  eded16(). The se
1bfd0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1bfe0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
1bff0 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 68 69   handle. The thi
1c000 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
1c010 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
1c020 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
1c030 31 36 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51  16BE], or.** [SQ
1c040 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
1c050 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
1c060 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
1c070 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
1c080 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
1c090 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
1c0a0 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
1c0b0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
1c0c0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
1c0d0 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
1c0e0 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20  sequence..**.** 
1c0f0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1c100 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
1c110 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
1c120 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
1c130 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
1c140 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
1c150 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
1c160 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
1c170 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
1c180 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1c190 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
1c1a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
1c1b0 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
1c1c0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
1c1d0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
1c1e0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
1c1f0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
1c200 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
1c210 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
1c220 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
1c230 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
1c240 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
1c250 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
1c260 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
1c270 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
1c280 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
1c290 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
1c2a0 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
1c2b0 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
1c2c0 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
1c2d0 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
1c2e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
1c2f0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
1c300 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
1c310 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
1c320 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
1c330 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
1c340 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
1c350 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1c360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c370 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
1c380 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
1c390 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
1c3a0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
1c3b0 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
1c3c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
1c3d0 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
1c3e0 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
1c3f0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
1c400 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
1c410 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
1c420 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
1c430 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
1c440 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
1c450 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1c460 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
1c470 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
1c480 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
1c490 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
1c4a0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
1c4b0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
1c4c0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
1c4d0 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
1c4e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1c4f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c500 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
1c510 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
1c520 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
1c530 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
1c540 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
1c550 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c560 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65  EF:  Suspend Exe
1c570 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
1c580 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68  rt Time.**.** Th
1c590 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
1c5a0 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
1c5b0 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
1c5c0 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 61 20   execution.** a 
1c5d0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
1c5e0 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
1c5f0 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
1c600 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
1c610 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1c620 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
1c630 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
1c640 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73   with .** millis
1c650 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
1c660 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
1c670 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
1c680 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74  nded up to .** t
1c690 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
1c6a0 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
1c6b0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1c6c0 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20   sleep actually 
1c6d0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
1c6e0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
1c6f0 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
1c700 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ned..**.** SQLit
1c710 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
1c720 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
1c730 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
1c740 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
1c750 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1c760 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1c770 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
1c780 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
1c790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1c7a0 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
1c7b0 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
1c7c0 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
1c7d0 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20   If this global 
1c7e0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
1c7f0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
1c800 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
1c810 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
1c820 66 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20 64 69  folder (a.ka. di
1c830 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
1c840 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
1c850 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
1c860 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
1c870 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
1c880 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68  irectory.  If th
1c890 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
1c8a0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  s NULL pointer, 
1c8b0 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f 65 73  then SQLite does
1c8c0 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
1c8d0 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 65 6d   appropriate tem
1c8e0 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64  porary.** file d
1c8f0 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
1c900 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
1c910 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  o modify this va
1c920 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 64 61  riable once a da
1c930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c940 6e 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70  n.** has been op
1c950 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74  ened.  It is int
1c960 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
1c970 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
1c980 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
1c990 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
1c9a0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
1c9b0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
1c9c0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
1c9d0 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
1c9e0 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20  call and remain 
1c9f0 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65 61  unchanged therea
1ca00 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  fter..*/.SQLITE_
1ca10 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
1ca20 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
1ca30 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
1ca40 33 52 45 46 3a 20 20 54 65 73 74 20 54 6f 20 53  3REF:  Test To S
1ca50 65 65 20 49 66 20 54 68 65 20 44 61 74 61 62 61  ee If The Databa
1ca60 73 65 20 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f  se Is In Auto-Co
1ca70 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 0a 2a 2a 20  mmit Mode.**.** 
1ca80 54 65 73 74 20 74 6f 20 73 65 65 20 77 68 65 74  Test to see whet
1ca90 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 64  her or not the d
1caa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cab0 6f 6e 20 69 73 20 69 6e 20 61 75 74 6f 63 6f 6d  on is in autocom
1cac0 6d 69 74 0a 2a 2a 20 6d 6f 64 65 2e 20 20 52 65  mit.** mode.  Re
1cad0 74 75 72 6e 20 54 52 55 45 20 69 66 20 69 74 20  turn TRUE if it 
1cae0 69 73 20 61 6e 64 20 46 41 4c 53 45 20 69 66 20  is and FALSE if 
1caf0 6e 6f 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74  not.  Autocommit
1cb00 20 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62   mode is on.** b
1cb10 79 20 64 65 66 61 75 6c 74 2e 20 20 41 75 74 6f  y default.  Auto
1cb20 63 6f 6d 6d 69 74 20 69 73 20 64 69 73 61 62 6c  commit is disabl
1cb30 65 64 20 62 79 20 61 20 42 45 47 49 4e 20 73 74  ed by a BEGIN st
1cb40 61 74 65 6d 65 6e 74 20 61 6e 64 20 72 65 65 6e  atement and reen
1cb50 61 62 6c 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  abled.** by the 
1cb60 6e 65 78 74 20 43 4f 4d 4d 49 54 20 6f 72 20 52  next COMMIT or R
1cb70 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 49  OLLBACK..**.** I
1cb80 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
1cb90 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
1cba0 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
1cbb0 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
1cbc0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
1cbd0 61 63 74 69 6f 6e 73 20 28 65 72 72 6f 72 73 20  actions (errors 
1cbe0 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
1cbf0 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
1cc00 5f 49 4f 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51  _IOERR], .** [SQ
1cc10 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
1cc20 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
1cc30 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
1cc40 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
1cc50 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
1cc60 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
1cc70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
1cc80 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
1cc90 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 69 66 20  .** find out if 
1cca0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
1ccb0 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
1ccc0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
1ccd0 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
1cce0 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
1ccf0 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
1cd00 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
1cd10 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
1cd20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
1cd30 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
1cd40 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
1cd50 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
1cd60 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
1cd70 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
1cd80 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  alue.** is undef
1cd90 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
1cda0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
1cdb0 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
1cdc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cdd0 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
1cde0 73 65 20 48 61 6e 64 6c 65 20 41 73 73 6f 63 69  se Handle Associ
1cdf0 61 74 65 64 20 57 69 74 68 20 41 20 50 72 65 70  ated With A Prep
1ce00 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
1ce10 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
1ce20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62  [sqlite3*] datab
1ce30 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 77 68  ase handle to wh
1ce40 69 63 68 20 61 0a 2a 2a 20 5b 73 71 6c 69 74 65  ich a.** [sqlite
1ce50 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  3_stmt | prepare
1ce60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
1ce70 6f 6e 67 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73  ongs..** This is
1ce80 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1ce90 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77  se handle that w
1cea0 61 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  as.** the first 
1ceb0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1cec0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ced0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
1cee0 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20 77  riants.** that w
1cef0 61 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  as used to creat
1cf00 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
1cf10 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
1cf20 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
1cf30 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
1cf40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
1cf50 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
1cf60 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
1cf70 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
1cf80 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
1cf90 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1cfa0 6e 65 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 20  nes.** register 
1cfb0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1cfc0 6e 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ns to be invoked
1cfd0 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
1cfe0 73 61 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 63 6f  saction.** is co
1cff0 6d 6d 69 74 74 65 64 20 6f 72 20 72 6f 6c 6c 65  mmitted or rolle
1d000 64 20 62 61 63 6b 2e 20 20 54 68 65 20 70 41 72  d back.  The pAr
1d010 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
1d020 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20  ssed through.** 
1d030 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  to the callback.
1d040 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63    If the callbac
1d050 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
1d060 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20  ok function .** 
1d070 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1d080 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  , then the commi
1d090 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  t is converted i
1d0a0 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
1d0b0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
1d0c0 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
1d0d0 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
1d0e0 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61  red, its pArg va
1d0f0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
1d100 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 4e 55  .** Otherwise NU
1d110 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
1d120 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e  **.** Registerin
1d130 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f  g a NULL functio
1d140 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  n disables the c
1d150 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46  allback..**.** F
1d160 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
1d170 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74  of this API, a t
1d180 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61  ransaction is sa
1d190 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 20  id to have been 
1d1a0 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
1d1b0 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
1d1c0 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
1d1d0 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
1d1e0 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
1d1f0 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
1d200 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
1d210 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
1d220 75 72 2e 20 54 68 65 20 0a 2a 2a 20 63 61 6c 6c  ur. The .** call
1d230 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
1d240 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
1d250 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69  tion is automati
1d260 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 0a 2a 2a 20  cally rolled.** 
1d270 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
1d280 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d290 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
1d2a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
1d2b0 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
1d2c0 65 72 66 61 63 65 73 20 61 6e 64 20 61 72 65 20  erfaces and are 
1d2d0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1d2e0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
1d2f0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
1d300 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
1d310 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
1d320 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
1d330 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
1d340 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
1d350 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
1d360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d370 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
1d380 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
1d390 63 6b 73 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  cks.**.** Regist
1d3a0 65 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  er a callback fu
1d3b0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
1d3c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d3d0 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62  ion identified b
1d3e0 79 20 74 68 65 20 0a 2a 2a 20 66 69 72 73 74 20  y the .** first 
1d3f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 62 65 20 69  argument to be i
1d400 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
1d410 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  a row is updated
1d420 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
1d430 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  leted..** Any ca
1d440 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
1d450 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
1d460 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 66   this function f
1d470 6f 72 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20  or the same .** 
1d480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d490 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
1d4a0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  n..**.** The sec
1d4b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
1d4c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1d4d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
1d4e0 6f 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20 72  oke when a .** r
1d4f0 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
1d500 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
1d510 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
1d520 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
1d530 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 61 20 63  llback is.** a c
1d540 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
1d550 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1d560 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
1d570 28 29 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 63  (). The second c
1d580 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75  allback .** argu
1d590 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 53  ment is one of S
1d5a0 51 4c 49 54 45 5f 49 4e 53 45 52 54 2c 20 53 51  QLITE_INSERT, SQ
1d5b0 4c 49 54 45 5f 44 45 4c 45 54 45 20 6f 72 20 53  LITE_DELETE or S
1d5c0 51 4c 49 54 45 5f 55 50 44 41 54 45 2c 20 64 65  QLITE_UPDATE, de
1d5d0 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 74 68  pending.** on th
1d5e0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
1d5f0 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
1d600 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b  back to be invok
1d610 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 6e  ed. The third an
1d620 64 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67  d .** fourth arg
1d630 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
1d640 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
1d650 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 64  ointers to the d
1d660 61 74 61 62 61 73 65 20 61 6e 64 20 0a 2a 2a 20  atabase and .** 
1d670 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61  table name conta
1d680 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74  ining the affect
1d690 65 64 20 72 6f 77 2e 20 54 68 65 20 66 69 6e 61  ed row. The fina
1d6a0 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
1d6b0 65 74 65 72 20 69 73 20 0a 2a 2a 20 74 68 65 20  eter is .** the 
1d6c0 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77  rowid of the row
1d6d0 2e 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66  . In the case of
1d6e0 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
1d6f0 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 61 66   is the rowid af
1d700 74 65 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61  ter .** the upda
1d710 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
1d720 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65  **.** The update
1d730 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
1d740 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
1d750 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
1d760 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
1d770 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
1d780 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
1d790 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a  sequence)..**.**
1d7a0 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63   If another func
1d7b0 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75  tion was previou
1d7c0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20  sly registered, 
1d7d0 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 20 69  its pArg value i
1d7e0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f  s returned..** O
1d7f0 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
1d800 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 76 6f   returned..*/.vo
1d810 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
1d820 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
1d830 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
1d840 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
1d850 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
1d860 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
1d870 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
1d880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d890 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  :  Enable Or Dis
1d8a0 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65  able Shared Page
1d8b0 72 20 43 61 63 68 65 0a 2a 2a 0a 2a 2a 20 54 68  r Cache.**.** Th
1d8c0 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
1d8d0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
1d8e0 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
1d8f0 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
1d900 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
1d910 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
1d920 65 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f  etween connectio
1d930 6e 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ns to the same d
1d940 61 74 61 62 61 73 65 2e 0a 2a 2a 20 53 68 61 72  atabase..** Shar
1d950 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ing is enabled i
1d960 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
1d970 73 20 74 72 75 65 20 61 6e 64 20 64 69 73 61 62  s true and disab
1d980 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
1d990 65 6e 74 0a 2a 2a 20 69 73 20 66 61 6c 73 65 2e  ent.** is false.
1d9a0 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67  .**.** Beginning
1d9b0 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
1d9c0 6f 6e 20 33 2e 35 2e 30 2c 20 63 61 63 68 65 20  on 3.5.0, cache 
1d9d0 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  sharing is enabl
1d9e0 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 0a  ed and disabled.
1d9f0 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65  ** for an entire
1da00 20 70 72 6f 63 65 73 73 2e 20 20 49 6e 20 70 72   process.  In pr
1da10 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ior versions of 
1da20 53 51 4c 69 74 65 2c 20 73 68 61 72 69 6e 67 20  SQLite, sharing 
1da30 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f  was.** enabled o
1da40 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65  r disabled for e
1da50 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72  ach thread separ
1da60 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ately..**.** The
1da70 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d   cache sharing m
1da80 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20  ode set by this 
1da90 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74  interface effect
1daa0 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  s all subsequent
1dab0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  .** calls to [sq
1dac0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1dad0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1dae0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1daf0 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45  _open16()]..** E
1db00 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65  xisting database
1db10 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e   connections con
1db20 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68  tinue use the sh
1db30 61 72 69 6e 67 20 6d 6f 64 65 20 74 68 61 74 20  aring mode that 
1db40 77 61 73 0a 2a 2a 20 69 6e 20 65 66 66 65 63 74  was.** in effect
1db50 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65   at the time the
1db60 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a  y were opened..*
1db70 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62  *.** Virtual tab
1db80 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73  les cannot be us
1db90 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64  ed with a shared
1dba0 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68   cache.  When sh
1dbb0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
1dbc0 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73   enabled, the [s
1dbd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
1dbe0 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64  dule()] API used
1dbf0 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
1dc00 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77  virtual tables w
1dc10 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
1dc20 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  n an error..**.*
1dc30 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
1dc40 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
1dc50 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
1dc60 68 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65  he was.** enable
1dc70 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75  d or disabled su
1dc80 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
1dc90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
1dca0 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69  error code].** i
1dcb0 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
1dcc0 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72  wise..**.** Shar
1dcd0 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
1dce0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
1dcf0 20 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74    But this might
1dd00 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
1dd10 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
1dd20 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
1dd30 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
1dd40 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
1dd50 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
1dd60 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
1dd70 6c 69 63 69 74 6c 79 2e 0a 2a 2f 0a 69 6e 74 20  licitly..*/.int 
1dd80 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
1dd90 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29  hared_cache(int)
1dda0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ddb0 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f 20 46  F:  Attempt To F
1ddc0 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a  ree Heap Memory.
1ddd0 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74 6f  **.** Attempt to
1dde0 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66   free N bytes of
1ddf0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
1de00 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
1de10 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 6d 65  -essential.** me
1de20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1de30 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
1de40 61 62 61 73 65 20 6c 69 62 72 61 72 79 20 28 65  abase library (e
1de50 78 61 6d 70 6c 65 3a 20 6d 65 6d 6f 72 79 20 0a  xample: memory .
1de60 2a 2a 20 75 73 65 64 20 74 6f 20 63 61 63 68 65  ** used to cache
1de70 20 64 61 74 61 62 61 73 65 20 70 61 67 65 73 20   database pages 
1de80 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  to improve perfo
1de90 72 6d 61 6e 63 65 29 2e 0a 2a 2f 0a 69 6e 74 20  rmance)..*/.int 
1dea0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
1deb0 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a  memory(int);../*
1dec0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 49  .** CAPI3REF:  I
1ded0 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
1dee0 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a   Heap Size.**.**
1def0 20 50 6c 61 63 65 20 61 20 22 73 6f 66 74 22 20   Place a "soft" 
1df00 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f  limit on the amo
1df10 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
1df20 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
1df30 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53  llocated.** by S
1df40 51 4c 69 74 65 2e 20 20 49 66 20 61 6e 20 69 6e  QLite.  If an in
1df50 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f  ternal allocatio
1df60 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 0a  n is requested .
1df70 2a 2a 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78  ** that would ex
1df80 63 65 65 64 20 74 68 65 20 73 70 65 63 69 66 69  ceed the specifi
1df90 65 64 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74  ed limit, [sqlit
1dfa0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
1dfb0 79 28 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  y()] is.** invok
1dfc0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
1dfd0 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20  imes to free up 
1dfe0 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72  some space befor
1dff0 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  e the allocation
1e000 0a 2a 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a  .** is made..**.
1e010 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  ** The limit is 
1e020 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62  called "soft", b
1e030 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74  ecause if [sqlit
1e040 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
1e050 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66  y()] cannot.** f
1e060 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d  ree sufficient m
1e070 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74  emory to prevent
1e080 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20   the limit from 
1e090 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a  being exceeded,.
1e0a0 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73  ** the memory is
1e0b0 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61   allocated anywa
1e0c0 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e  y and the curren
1e0d0 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  t operation proc
1e0e0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65  eeds..**.** A ne
1e0f0 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76  gative or zero v
1e100 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73  alue for N means
1e110 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e   that there is n
1e120 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  o soft heap limi
1e130 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  t and.** [sqlite
1e140 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
1e150 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65  ()] will only be
1e160 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d   called when mem
1e170 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65 64  ory is exhausted
1e180 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
1e190 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73   value for the s
1e1a0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
1e1b0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51  s zero..**.** SQ
1e1c0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73  Lite makes a bes
1e1d0 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f  t effort to hono
1e1e0 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
1e1f0 6c 69 6d 69 74 2e 20 20 42 75 74 20 69 66 20 69  limit.  But if i
1e200 74 0a 2a 2a 20 69 73 20 75 6e 61 62 6c 65 20 74  t.** is unable t
1e210 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20  o reduce memory 
1e220 75 73 61 67 65 20 62 65 6c 6f 77 20 74 68 65 20  usage below the 
1e230 73 6f 66 74 20 6c 69 6d 69 74 2c 20 65 78 65 63  soft limit, exec
1e240 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f  ution will.** co
1e250 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65  ntinue without e
1e260 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61  rror or notifica
1e270 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77  tion.  This is w
1e280 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  hy the limit is 
1e290 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f  .** called a "so
1e2a0 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69  ft" limit.  It i
1e2b0 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e  s advisory only.
1e2c0 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1e2d0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1e2e0 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69  .5.0, this routi
1e2f0 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69  ne only constrai
1e300 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ned the memory.*
1e310 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61  * allocated by a
1e320 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d   single thread -
1e330 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
1e340 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20 72   in which this r
1e350 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20  outine.** runs. 
1e360 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
1e370 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1e380 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68  .5.0, the soft h
1e390 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20  eap limit is.** 
1e3a0 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74  applied to all t
1e3b0 68 72 65 61 64 73 2e 20 20 54 68 65 20 76 61 6c  hreads.  The val
1e3c0 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72  ue specified for
1e3d0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
1e3e0 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70  imit.** is an up
1e3f0 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65  per bound on the
1e400 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c   total memory al
1e410 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c  location for all
1e420 20 74 68 72 65 61 64 73 2e 20 20 49 6e 0a 2a 2a   threads.  In.**
1e430 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74   version 3.5.0 t
1e440 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61  here is no mecha
1e450 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e  nism for limitin
1e460 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65  g the heap usage
1e470 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75   for.** individu
1e480 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  al threads..*/.v
1e490 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  oid sqlite3_soft
1e4a0 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29  _heap_limit(int)
1e4b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e4c0 46 3a 20 20 45 78 74 72 61 63 74 20 4d 65 74 61  F:  Extract Meta
1e4d0 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
1e4e0 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a  umn Of A Table.*
1e4f0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1e500 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65 74  e.** returns met
1e510 61 2d 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  a-data about a s
1e520 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
1e530 66 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74  f a specific dat
1e540 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61  abase.** table a
1e550 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
1e560 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68  the connection h
1e570 61 6e 64 6c 65 20 70 61 73 73 65 64 20 61 73 20  andle passed as 
1e580 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
1e590 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  on .** argument.
1e5a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d  .**.** The colum
1e5b0 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20  n is identified 
1e5c0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74  by the second, t
1e5d0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
1e5e0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a  parameters to .*
1e5f0 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  * this function.
1e600 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
1e610 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20  meter is either 
1e620 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1e630 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65  database.** (i.e
1e640 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22  . "main", "temp"
1e650 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20   or an attached 
1e660 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69  database) contai
1e670 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69  ning the specifi
1e680 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e  ed.** table or N
1e690 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55  ULL. If it is NU
1e6a0 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74  LL, then all att
1e6b0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20  ached databases 
1e6c0 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20  are searched.** 
1e6d0 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73  for the table us
1e6e0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
1e6f0 6f 72 69 74 68 6d 20 61 73 20 74 68 65 20 64 61  orithm as the da
1e700 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73  tabase engine us
1e710 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76  es to .** resolv
1e720 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61  e unqualified ta
1e730 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a  ble references..
1e740 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
1e750 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
1e760 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
1e770 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74  nction are the t
1e780 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
1e790 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
1e7a0 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20  desired column, 
1e7b0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65  respectively. Ne
1e7c0 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70  ither of these p
1e7d0 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61  arameters .** ma
1e7e0 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  y be NULL..**.**
1e7f0 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f   Meta informatio
1e800 6e 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  n is returned by
1e810 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
1e820 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
1e830 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
1e840 65 20 35 74 68 20 61 6e 64 20 73 75 62 73 65 71  e 5th and subseq
1e850 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
1e860 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
1e870 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 0a  . Any of these .
1e880 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79  ** arguments may
1e890 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69   be NULL, in whi
1e8a0 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72  ch case the corr
1e8b0 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e  esponding elemen
1e8c0 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e  t of meta .** in
1e8d0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d  formation is omm
1e8e0 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72  itted..**.** <pr
1e8f0 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20  e>.** Parameter 
1e900 20 20 20 20 4f 75 74 70 75 74 20 54 79 70 65 20      Output Type 
1e910 20 20 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e       Description
1e920 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  .** ------------
1e930 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1e940 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20  -------.**.**   
1e950 35 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73  5th         cons
1e960 74 20 63 68 61 72 2a 20 20 20 20 20 20 44 61 74  t char*      Dat
1e970 61 20 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20  a type.**   6th 
1e980 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68          const ch
1e990 61 72 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66  ar*      Name of
1e9a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c   the default col
1e9b0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
1e9c0 0a 2a 2a 20 20 20 37 74 68 20 20 20 20 20 20 20  .**   7th       
1e9d0 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20    int           
1e9e0 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63     True if the c
1e9f0 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20  olumn has a NOT 
1ea00 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a  NULL constraint.
1ea10 2a 2a 20 20 20 38 74 68 20 20 20 20 20 20 20 20  **   8th        
1ea20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20   int            
1ea30 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f    True if the co
1ea40 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20  lumn is part of 
1ea50 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a  the PRIMARY KEY.
1ea60 2a 2a 20 20 20 39 74 68 20 20 20 20 20 20 20 20  **   9th        
1ea70 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20   int            
1ea80 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f    True if the co
1ea90 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52  lumn is AUTOINCR
1eaa0 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a  EMENT.** </pre>.
1eab0 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d  **.**.** The mem
1eac0 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ory pointed to b
1ead0 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20  y the character 
1eae0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
1eaf0 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65  d for the .** de
1eb00 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
1eb10 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
1eb20 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
1eb30 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
1eb40 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61  xt .** call to a
1eb50 6e 79 20 73 71 6c 69 74 65 20 41 50 49 20 66 75  ny sqlite API fu
1eb60 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
1eb70 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74   the specified t
1eb80 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79  able is actually
1eb90 20 61 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e   a view, then an
1eba0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1ebb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
1ebc0 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d   specified colum
1ebd0 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f  n is "rowid", "o
1ebe0 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22  id" or "_rowid_"
1ebf0 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45   and an .** INTE
1ec00 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20  GER PRIMARY KEY 
1ec10 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20  column has been 
1ec20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
1ec30 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  red, then the ou
1ec40 74 70 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74  tput .** paramet
1ec50 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20  ers are set for 
1ec60 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64  the explicitly d
1ec70 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20  eclared column. 
1ec80 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a  If there is no.*
1ec90 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  * explicitly dec
1eca0 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e  lared IPK column
1ecb0 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
1ecc0 74 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  t parameters are
1ecd0 20 73 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c   set as .** foll
1ece0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ows:.**.** <pre>
1ecf0 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70  .**     data typ
1ed00 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20  e: "INTEGER".** 
1ed10 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65      collation se
1ed20 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22  quence: "BINARY"
1ed30 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c  .**     not null
1ed40 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61  : 0.**     prima
1ed50 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20  ry key: 1.**    
1ed60 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a   auto increment:
1ed70 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a   0.** </pre>.**.
1ed80 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
1ed90 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72   may load one or
1eda0 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72   more schemas fr
1edb0 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  om database file
1edc0 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f  s. If an.** erro
1edd0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
1ede0 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72  this process, or
1edf0 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65   if the requeste
1ee00 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  d table or colum
1ee10 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66  n.** cannot be f
1ee20 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20  ound, an SQLITE 
1ee30 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
1ee40 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
1ee50 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c  ror message.** l
1ee60 65 66 74 20 69 6e 20 74 68 65 20 64 61 74 61 62  eft in the datab
1ee70 61 73 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62  ase handle (to b
1ee80 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e  e retrieved usin
1ee90 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  g sqlite3_errmsg
1eea0 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ())..**.** This 
1eeb0 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  API is only avai
1eec0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
1eed0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
1eee0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
1eef0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
1ef00 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70  MN_METADATA prep
1ef10 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
1ef20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
1ef30 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f  sqlite3_table_co
1ef40 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20  lumn_metadata(. 
1ef50 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1ef60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1ef70 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  Connection handl
1ef80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1ef90 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
1efa0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e     /* Database n
1efb0 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20  ame or NULL */. 
1efc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
1efd0 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20  bleName,     /* 
1efe0 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  Table name */.  
1eff0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
1f000 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43  umnName,    /* C
1f010 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20  olumn name */.  
1f020 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44  char const **pzD
1f030 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f  ataType,    /* O
1f040 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20  UTPUT: Declared 
1f050 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63  data type */.  c
1f060 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f  har const **pzCo
1f070 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55  llSeq,     /* OU
1f080 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  TPUT: Collation 
1f090 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f  sequence name */
1f0a0 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c  .  int *pNotNull
1f0b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1f0c0 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
1f0d0 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74  f NOT NULL const
1f0e0 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a  raint exists */.
1f0f0 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b    int *pPrimaryK
1f100 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ey,           /*
1f110 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
1f120 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20   column part of 
1f130 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75  PK */.  int *pAu
1f140 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20  toinc           
1f150 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
1f160 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
1f170 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20   auto-increment 
1f180 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1f190 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45  I3REF: Load An E
1f1a0 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41  xtension.**.** A
1f1b0 74 74 65 6d 70 74 20 74 6f 20 6c 6f 61 64 20 61  ttempt to load a
1f1c0 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  n SQLite extensi
1f1d0 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
1f1e0 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
1f1f0 0a 2a 2a 20 7a 46 69 6c 65 2e 20 20 54 68 65 20  .** zFile.  The 
1f200 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a  entry point is z
1f210 50 72 6f 63 2e 20 20 7a 50 72 6f 63 20 6d 61 79  Proc.  zProc may
1f220 20 62 65 20 30 20 69 6e 20 77 68 69 63 68 20 63   be 0 in which c
1f230 61 73 65 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20  ase the.** name 
1f240 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
1f250 6e 74 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22  nt defaults to "
1f260 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f  sqlite3_extensio
1f270 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 52  n_init"..**.** R
1f280 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1f290 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
1f2a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
1f2b0 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65  if something goe
1f2c0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  s wrong..**.** I
1f2d0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
1f2e0 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69  s and pzErrMsg i
1f2f0 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 66 69  s not 0, then fi
1f300 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74  ll *pzErrMsg wit
1f310 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73  h .** error mess
1f320 61 67 65 20 74 65 78 74 2e 20 20 54 68 65 20 63  age text.  The c
1f330 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
1f340 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73  should free this
1f350 20 6d 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61   memory.** by ca
1f360 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  lling [sqlite3_f
1f370 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78  ree()]..**.** Ex
1f380 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
1f390 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20  must be enabled 
1f3a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
1f3b0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
1f3c0 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72  sion()].** prior
1f3d0 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   to calling this
1f3e0 20 41 50 49 20 6f 72 20 61 6e 20 65 72 72 6f 72   API or an error
1f3f0 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
1f400 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
1f410 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
1f420 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1f430 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61            /* Loa
1f440 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  d the extension 
1f450 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61  into this databa
1f460 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f  se connection */
1f470 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1f480 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65  File,    /* Name
1f490 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c   of the shared l
1f4a0 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ibrary containin
1f4b0 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20  g extension */. 
1f4c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72   const char *zPr
1f4d0 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20  oc,    /* Entry 
1f4e0 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20  point.  Derived 
1f4f0 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20  from zFile if 0 
1f500 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1f510 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75  rMsg       /* Pu
1f520 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  t error message 
1f530 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f  here if not 0 */
1f540 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1f550 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20  REF:  Enable Or 
1f560 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f  Disable Extensio
1f570 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20  n Loading.**.** 
1f580 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65  So as not to ope
1f590 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73  n security holes
1f5a0 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63   in older applic
1f5b0 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a  ations that are.
1f5c0 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f  ** unprepared to
1f5d0 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e   deal with exten
1f5e0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e  sion loading, an
1f5f0 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20  d as a means of 
1f600 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74  disabling.** ext
1f610 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77  ension loading w
1f620 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20  hile evaluating 
1f630 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
1f640 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a  , the following.
1f650 2a 2a 20 41 50 49 20 69 73 20 70 72 6f 76 69 64  ** API is provid
1f660 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b  ed to turn the [
1f670 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
1f680 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e  ension()] mechan
1f690 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66  ism on and.** of
1f6a0 66 2e 20 20 49 74 20 69 73 20 6f 66 66 20 62 79  f.  It is off by
1f6b0 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 74   default.  See t
1f6c0 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a  icket #1863..**.
1f6d0 2a 2a 20 43 61 6c 6c 20 74 68 69 73 20 72 6f 75  ** Call this rou
1f6e0 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d  tine with onoff=
1f6f0 3d 31 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e  =1 to turn exten
1f700 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a  sion loading on.
1f710 2a 2a 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77  ** and call it w
1f720 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20  ith onoff==0 to 
1f730 74 75 72 6e 20 69 74 20 62 61 63 6b 20 6f 66 66  turn it back off
1f740 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73   again..*/.int s
1f750 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
1f760 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c  ad_extension(sql
1f770 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e  ite3 *db, int on
1f780 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
1f790 49 33 52 45 46 3a 20 4d 61 6b 65 20 41 72 72 61  I3REF: Make Arra
1f7a0 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f  ngements To Auto
1f7b0 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41  matically Load A
1f7c0 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a  n Extension.**.*
1f7d0 2a 20 52 65 67 69 73 74 65 72 20 61 6e 20 65 78  * Register an ex
1f7e0 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f  tension entry po
1f7f0 69 6e 74 20 74 68 61 74 20 69 73 20 61 75 74 6f  int that is auto
1f800 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65  matically invoke
1f810 64 0a 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20  d.** whenever a 
1f820 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
1f830 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
1f840 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
1f850 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1f860 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1f870 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1f880 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  n_v2()]..**.** T
1f890 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69  his API can be i
1f8a0 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61  nvoked at progra
1f8b0 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64  m startup in ord
1f8c0 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a  er to register.*
1f8d0 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74  * one or more st
1f8e0 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20  atically linked 
1f8f0 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20  extensions that 
1f900 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c  will be availabl
1f910 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20  e.** to all new 
1f920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f930 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 44 75 70 6c  ions..**.** Dupl
1f940 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73  icate extensions
1f950 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f   are detected so
1f960 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   calling this ro
1f970 75 74 69 6e 65 20 6d 75 6c 74 69 70 6c 65 0a 2a  utine multiple.*
1f980 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
1f990 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20   same extension 
1f9a0 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a  is harmless..**.
1f9b0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1f9c0 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72  stores a pointer
1f9d0 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f   to the extensio
1f9e0 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a  n in an array.**
1f9f0 20 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65   that is obtaine
1fa00 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2e  d from malloc().
1fa10 20 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d    If you run a m
1fa20 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20 63 68  emory leak.** ch
1fa30 65 63 6b 65 72 20 6f 6e 20 79 6f 75 72 20 70 72  ecker on your pr
1fa40 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70  ogram and it rep
1fa50 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61  orts a leak beca
1fa60 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 61  use of this.** a
1fa70 72 72 61 79 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rray, then invok
1fa80 65 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d  e [sqlite3_autom
1fa90 61 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e 5f 72  atic_extension_r
1faa0 65 73 65 74 28 29 5d 20 70 72 69 6f 72 0a 2a 2a  eset()] prior.**
1fab0 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20   to shutdown to 
1fac0 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e  free the memory.
1fad0 0a 2a 2a 0a 2a 2a 20 41 75 74 6f 6d 61 74 69 63  .**.** Automatic
1fae0 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c   extensions appl
1faf0 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72  y across all thr
1fb00 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eads..**.** This
1fb10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78   interface is ex
1fb20 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1fb30 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  s subject to cha
1fb40 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61  nge or.** remova
1fb50 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  l in future rele
1fb60 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
1fb70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  */.int sqlite3_a
1fb80 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
1fb90 69 64 20 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29  id *xEntryPoint)
1fba0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
1fbb0 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61  EF: Reset Automa
1fbc0 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  tic Extension Lo
1fbd0 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 44 69 73 61  ading.**.** Disa
1fbe0 62 6c 65 20 61 6c 6c 20 70 72 65 76 69 6f 75 73  ble all previous
1fbf0 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75  ly registered au
1fc00 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
1fc10 6e 73 2e 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75  ns.  This.** rou
1fc20 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
1fc30 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72  effect of all pr
1fc40 69 6f 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74  ior [sqlite3_aut
1fc50 6f 6d 61 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e  omatic_extension
1fc60 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a  ()].** calls..**
1fc70 0a 2a 2a 20 54 68 69 73 20 63 61 6c 6c 20 64 69  .** This call di
1fc80 73 61 62 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  sabled automatic
1fc90 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
1fca0 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a  ll threads..**.*
1fcb0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1fcc0 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
1fcd0 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20   and is subject 
1fce0 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  to change or.** 
1fcf0 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
1fd00 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
1fd10 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  Lite..*/.void sq
1fd20 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
1fd30 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29  _extension(void)
1fd40 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58  ;.../*.****** EX
1fd50 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62  PERIMENTAL - sub
1fd60 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77  ject to change w
1fd70 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a  ithout notice **
1fd80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
1fd90 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
1fda0 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
1fdb0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
1fdc0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
1fdd0 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
1fde0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
1fdf0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
1fe00 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
1fe10 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
1fe20 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
1fe30 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
1fe40 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
1fe50 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
1fe60 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
1fe70 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
1fe80 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
1fe90 73 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69  stablizes, we wi
1fea0 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
1feb0 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
1fec0 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
1fed0 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
1fee0 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
1fef0 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
1ff00 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
1ff10 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
1ff20 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
1ff30 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1ff40 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
1ff50 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
1ff60 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1ff70 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
1ff80 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
1ff90 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1ffa0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
1ffb0 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
1ffc0 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
1ffd0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1ffe0 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
1fff0 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20  odule;../*.** A 
20000 6d 6f 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73  module is a clas
20010 73 20 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62  s of virtual tab
20020 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  les.  Each modul
20030 65 20 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20  e is defined.** 
20040 62 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  by an instance o
20050 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
20060 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 69 73  structure.  This
20070 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69   structure consi
20080 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66  sts.** mostly of
20090 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   methods for the
200a0 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75   module..*/.stru
200b0 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
200c0 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  e {.  int iVersi
200d0 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65  on;.  int (*xCre
200e0 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ate)(sqlite3*, v
200f0 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
20100 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
20110 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
20120 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
20130 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
20140 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
20150 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
20160 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c   (*xConnect)(sql
20170 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
20180 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
20190 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
201a0 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
201b0 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
201c0 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
201d0 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
201e0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74  );.  int (*xBest
201f0 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76  Index)(sqlite3_v
20200 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69  tab *pVTab, sqli
20210 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29  te3_index_info*)
20220 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f  ;.  int (*xDisco
20230 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76  nnect)(sqlite3_v
20240 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
20250 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73  nt (*xDestroy)(s
20260 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
20270 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70  ab);.  int (*xOp
20280 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  en)(sqlite3_vtab
20290 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33   *pVTab, sqlite3
202a0 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70  _vtab_cursor **p
202b0 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20  pCursor);.  int 
202c0 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
202d0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
202e0 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72  .  int (*xFilter
202f0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
20300 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e  ursor*, int idxN
20310 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  um, const char *
20320 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20  idxStr,.        
20330 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
20340 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  , sqlite3_value 
20350 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28  **argv);.  int (
20360 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f  *xNext)(sqlite3_
20370 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
20380 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c   int (*xEof)(sql
20390 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
203a0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c  *);.  int (*xCol
203b0 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  umn)(sqlite3_vta
203c0 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74  b_cursor*, sqlit
203d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
203e0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69  );.  int (*xRowi
203f0 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  d)(sqlite3_vtab_
20400 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
20410 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b  _int64 *pRowid);
20420 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65  .  int (*xUpdate
20430 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
20440 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76  , int, sqlite3_v
20450 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33  alue **, sqlite3
20460 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74  _int64 *);.  int
20470 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74   (*xBegin)(sqlit
20480 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
20490 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
204a0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
204b0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  Tab);.  int (*xC
204c0 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76  ommit)(sqlite3_v
204d0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
204e0 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28  nt (*xRollback)(
204f0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
20500 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Tab);.  int (*xF
20510 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c  indFunction)(sql
20520 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
20530 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73  , int nArg, cons
20540 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20  t char *zName,. 
20550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20560 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78        void (**px
20570 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
20580 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
20590 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20  e3_value**),.   
205a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
205b0 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67      void **ppArg
205c0 29 3b 0a 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e  );..  int (*xRen
205d0 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ame)(sqlite3_vta
205e0 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20  b *pVtab, const 
205f0 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a  char *zNew);.};.
20600 0a 2f 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ./*.** The sqlit
20610 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
20620 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20  ructure and its 
20630 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73  substructures is
20640 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73   used to.** pass
20650 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74   information int
20660 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68  o and receive th
20670 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65  e reply from the
20680 20 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d   xBestIndex.** m
20690 65 74 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69  ethod of an sqli
206a0 74 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65  te3_module.  The
206b0 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a   fields under **
206c0 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65  Inputs** are the
206d0 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42  .** inputs to xB
206e0 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65  estIndex and are
206f0 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65   read-only.  xBe
20700 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20  stIndex inserts 
20710 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  its.** results i
20720 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74  nto the **Output
20730 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a  s** fields..**.*
20740 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  * The aConstrain
20750 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64  t[] array record
20760 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  s WHERE clause c
20770 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68  onstraints of th
20780 65 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a  e.** form:.**.**
20790 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20           column 
207a0 4f 50 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68  OP expr.**.** Wh
207b0 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 3c 2c 20  ere OP is =, <, 
207c0 3c 3d 2c 20 3e 2c 20 6f 72 20 3e 3d 2e 20 20 54  <=, >, or >=.  T
207d0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70  he particular op
207e0 65 72 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64  erator is stored
207f0 0a 2a 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69  .** in aConstrai
20800 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e  nt[].op.  The in
20810 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
20820 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a  n is stored in .
20830 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ** aConstraint[]
20840 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73  .iColumn.  aCons
20850 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
20860 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
20870 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
20880 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
20890 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
208a0 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
208b0 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
208c0 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
208d0 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a  if it cannot..**
208e0 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65  .** The optimize
208f0 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  r automatically 
20900 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66  inverts terms of
20910 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20   the form "expr 
20920 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e  OP column".** an
20930 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69  d makes other si
20940 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f  mplifications to
20950 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
20960 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  e in an attempt 
20970 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e  to.** get as man
20980 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  y WHERE clause t
20990 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f  erms into the fo
209a0 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61  rm shown above a
209b0 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54  s possible..** T
209c0 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
209d0 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f   array only repo
209e0 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65  rts WHERE clause
209f0 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f   terms in the co
20a00 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68  rrect.** form th
20a10 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20  at refer to the 
20a20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75  particular virtu
20a30 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71  al table being q
20a40 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ueried..**.** In
20a50 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
20a60 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
20a70 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e  use is stored in
20a80 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20   aOrderBy[]..** 
20a90 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72  Each term of aOr
20aa0 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20  derBy records a 
20ab0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52  column of the OR
20ac0 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a  DER BY clause..*
20ad0 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e  *.** The xBestIn
20ae0 64 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  dex method must 
20af0 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74  fill aConstraint
20b00 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66  Usage[] with inf
20b10 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
20b20 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72  t what parameter
20b30 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69  s to pass to xFi
20b40 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e  lter.  If argvIn
20b50 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68  dex>0 then.** th
20b60 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
20b70 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70  e of the corresp
20b80 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69  onding aConstrai
20b90 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65  nt[] is evaluate
20ba0 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73  d.** and becomes
20bb0 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74   the argvIndex-t
20bc0 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e  h entry in argv.
20bd0 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74    If aConstraint
20be0 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20  Usage[].omit.** 
20bf0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
20c00 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  e constraint is 
20c10 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75  assumed to be fu
20c20 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74  lly handled by t
20c30 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  he.** virtual ta
20c40 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63  ble and is not c
20c50 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20  hecked again by 
20c60 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
20c70 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  e idxNum and idx
20c80 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72  Ptr values are r
20c90 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73  ecorded and pass
20ca0 65 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e  ed into xFilter.
20cb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
20cc0 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 66 72  () is used to fr
20cd0 65 65 20 69 64 78 50 74 72 20 69 66 20 6e 65 65  ee idxPtr if nee
20ce0 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73  dToFreeIdxPtr is
20cf0 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   true..**.** The
20d00 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64   orderByConsumed
20d10 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70   means that outp
20d20 75 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20  ut from xFilter 
20d30 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a  will occur in.**
20d40 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64   the correct ord
20d50 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68  er to satisfy th
20d60 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
20d70 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70  e so that no sep
20d80 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67  arate.** sorting
20d90 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65   step is require
20da0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74  d..**.** The est
20db0 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65  imatedCost value
20dc0 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20   is an estimate 
20dd0 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64  of the cost of d
20de0 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74  oing the.** part
20df0 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20  icular lookup.  
20e00 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61  A full scan of a
20e10 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e   table with N en
20e20 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
20e30 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e  e.** a cost of N
20e40 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72  .  A binary sear
20e50 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66  ch of a table of
20e60 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
20e70 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74  d have a.** cost
20e80 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c   of approximatel
20e90 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72  y log(N)..*/.str
20ea0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
20eb0 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e  x_info {.  /* In
20ec0 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43  puts */.  int nC
20ed0 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
20ee0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
20ef0 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f  f entries in aCo
20f00 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74  nstraint */.  st
20f10 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
20f20 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a  ex_constraint {.
20f30 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
20f40 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
20f50 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74  * Column on left
20f60 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f  -hand side of co
20f70 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20  nstraint */.    
20f80 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
20f90 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f  p;         /* Co
20fa0 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f  nstraint operato
20fb0 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
20fc0 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20  ed char usable; 
20fd0 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74      /* True if t
20fe0 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  his constraint i
20ff0 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20  s usable */.    
21000 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74   int iTermOffset
21010 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73  ;          /* Us
21020 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20  ed internally - 
21030 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c  xBestIndex shoul
21040 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20  d ignore */.  } 
21050 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20  *aConstraint;   
21060 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c           /* Tabl
21070 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73  e of WHERE claus
21080 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f  e constraints */
21090 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b  .  int nOrderBy;
210a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
210b0 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   Number of terms
210c0 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59   in the ORDER BY
210d0 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72   clause */.  str
210e0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
210f0 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20  x_orderby {.    
21100 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
21110 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
21120 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  lumn number */. 
21130 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
21140 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a  r desc;       /*
21150 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20   True for DESC. 
21160 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20   False for ASC. 
21170 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79  */.  } *aOrderBy
21180 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
21190 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20  /* The ORDER BY 
211a0 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20  clause */..  /* 
211b0 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72  Outputs */.  str
211c0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
211d0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61  x_constraint_usa
211e0 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67  ge {.    int arg
211f0 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20  vIndex;         
21200 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73    /* if >0, cons
21210 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f  traint is part o
21220 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65  f argv to xFilte
21230 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65  r */.    unsigne
21240 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20  d char omit;    
21250 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65    /* Do not code
21260 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73   a test for this
21270 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
21280 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55   } *aConstraintU
21290 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e  sage;.  int idxN
212a0 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  um;             
212b0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65     /* Number use
212c0 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68  d to identify th
212d0 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61  e index */.  cha
212e0 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
212f0 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
21300 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
21310 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
21320 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e  3_malloc */.  in
21330 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53  t needToFreeIdxS
21340 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65  tr;      /* Free
21350 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71   idxStr using sq
21360 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20  lite3_free() if 
21370 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72  true */.  int or
21380 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20  derByConsumed;  
21390 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
213a0 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64  output is alread
213b0 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64  y ordered */.  d
213c0 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43  ouble estimatedC
213d0 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74  ost;      /* Est
213e0 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75  imated cost of u
213f0 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20  sing this index 
21400 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51  */.};.#define SQ
21410 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
21420 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64  RAINT_EQ    2.#d
21430 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
21440 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54  EX_CONSTRAINT_GT
21450 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
21460 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
21470 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64  RAINT_LE    8.#d
21480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
21490 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54  EX_CONSTRAINT_LT
214a0 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
214b0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
214c0 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a  TRAINT_GE    32.
214d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
214e0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
214f0 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20  MATCH 64../*.** 
21500 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
21510 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
21520 20 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61   a new module na
21530 6d 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74  me with an SQLit
21540 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
21550 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d    Module names m
21560 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
21570 64 20 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e  d before creatin
21580 67 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c  g new.** virtual
21590 20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d   tables on the m
215a0 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65  odule, or before
215b0 20 75 73 69 6e 67 20 70 72 65 65 78 69 73 74 69   using preexisti
215c0 6e 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  ng virtual.** ta
215d0 62 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  bles of the modu
215e0 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  le..*/.int sqlit
215f0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
21600 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
21610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
21620 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
21630 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
21640 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
21650 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
21660 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
21670 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
21680 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
21690 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20  ite3_module *,  
216a0 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
216b0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
216c0 20 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20   void *         
216d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
216e0 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
216f0 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
21700 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69  */.);../*.** Thi
21710 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65  s routine is ide
21720 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71  ntical to the sq
21730 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
21740 75 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f  ule() method abo
21750 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ve,.** except th
21760 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64  at it allows a d
21770 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
21780 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69  on to be specifi
21790 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65  ed. It is.** eve
217a0 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e  n more experimen
217b0 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73  tal than the res
217c0 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  t of the virtual
217d0 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a   tables API..*/.
217e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
217f0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20  te_module_v2(.  
21800 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
21810 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
21820 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
21830 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
21840 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
21850 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
21860 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
21870 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
21880 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
21890 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a  _module *,    /*
218a0 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
218b0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
218c0 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
218d0 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
218e0 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
218f0 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20  te/xConnect */. 
21900 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
21910 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d  (void*)     /* M
21920 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72  odule destructor
21930 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a   function */.);.
21940 0a 2f 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64  ./*.** Every mod
21950 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
21960 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
21970 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ss of the follow
21980 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ing structure.**
21990 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70   to describe a p
219a0 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
219b0 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ce of the module
219c0 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73  .  Each subclass
219d0 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c   will.** be tail
219e0 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63  ored to the spec
219f0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68  ific needs of th
21a00 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  e module impleme
21a10 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a  ntation.   The.*
21a20 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69  * purpose of thi
21a30 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20  s superclass is 
21a40 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69  to define certai
21a50 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72  n fields that ar
21a60 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61  e common.** to a
21a70 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ll module implem
21a80 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  entations..**.**
21a90 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
21aa0 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20  methods can set 
21ab0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
21ac0 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a   by assigning a.
21ad0 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  ** string obtain
21ae0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
21af0 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72  mprintf() to zEr
21b00 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f  rMsg.  The metho
21b10 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65  d should.** take
21b20 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70   care that any p
21b30 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66  rior string is f
21b40 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  reed by a call t
21b50 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
21b60 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73  .** prior to ass
21b70 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72  igning a new str
21b80 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ing to zErrMsg. 
21b90 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   After the error
21ba0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
21bb0 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
21bc0 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
21bd0 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
21be0 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
21bf0 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
21c00 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
21c10 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
21c20 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
21c30 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a   zeroed.  Note.*
21c40 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d  * that sqlite3_m
21c50 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
21c60 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20  ite3_free() are 
21c70 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72  used on the zErr
21c80 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e  Msg field.** sin
21c90 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ce virtual table
21ca0 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69  s are commonly i
21cb0 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f  mplemented in lo
21cc0 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
21cd0 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f  s which.** do no
21ce0 74 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f  t have access to
21cf0 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28   sqlite3MPrintf(
21d00 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65  ) or sqlite3Free
21d10 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ()..*/.struct sq
21d20 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
21d30 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
21d40 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
21d50 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
21d60 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
21d70 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
21d80 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
21d90 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
21da0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20   internally */. 
21db0 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
21dc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21dd0 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
21de0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
21df0 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
21e00 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
21e10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
21e20 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
21e30 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
21e40 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76  lds */.};../* Ev
21e50 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ery module imple
21e60 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
21e70 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
21e80 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
21e90 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72  ture.** to descr
21ea0 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74  ibe cursors that
21eb0 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20   point into the 
21ec0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e  virtual table an
21ed0 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
21ee0 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
21ef0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
21f00 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
21f10 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
21f20 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  ** xOpen method 
21f30 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
21f40 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  Each module impl
21f50 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
21f60 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f  define.** the co
21f70 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f  ntent of a curso
21f80 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73  r structure to s
21f90 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64  uit its own need
21fa0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75  s..**.** This su
21fb0 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20  perclass exists 
21fc0 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69  in order to defi
21fd0 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65  ne fields of the
21fe0 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20   cursor that.** 
21ff0 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  are common to al
22000 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  l implementation
22010 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  s..*/.struct sql
22020 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
22030 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61   {.  sqlite3_vta
22040 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f  b *pVtab;      /
22050 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
22060 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a  of this cursor *
22070 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
22080 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
22090 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
220a0 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
220b0 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
220c0 0a 2f 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61  ./*.** The xCrea
220d0 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20  te and xConnect 
220e0 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64  methods of a mod
220f0 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c  ule use the foll
22100 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20  owing API.** to 
22110 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d  declare the form
22120 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e  at (the names an
22130 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74  d datatypes of t
22140 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a  he columns) of.*
22150 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  * the virtual ta
22160 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d  bles they implem
22170 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
22180 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
22190 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
221a0 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61   char *zCreateTa
221b0 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72  ble);../*.** Vir
221c0 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20  tual tables can 
221d0 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74  provide alternat
221e0 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
221f0 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ons of functions
22200 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46  .** using the xF
22210 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68  indFunction meth
22220 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20  od.  But global 
22230 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73  versions of thos
22240 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d  e functions.** m
22250 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64  ust exist in ord
22260 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61  er to be overloa
22270 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ded..**.** This 
22280 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61  API makes sure a
22290 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20   global version 
222a0 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  of a function wi
222b0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
222c0 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62  ** name and numb
222d0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
222e0 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20   exists.  If no 
222f0 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78  such function ex
22300 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ists.** before t
22310 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65  his API is calle
22320 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f  d, a new functio
22330 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  n is created.  T
22340 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
22350 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20  n.** of the new 
22360 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20  function always 
22370 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74  causes an except
22380 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e  ion to be thrown
22390 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77  .  So.** the new
223a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
223b0 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69   good for anythi
223c0 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49  ng by itself.  I
223d0 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f  ts only.** purpo
223e0 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c  se is to be a pl
223f0 61 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74  ace-holder funct
22400 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20  ion that can be 
22410 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79  overloaded.** by
22420 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e   virtual tables.
22430 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
22440 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64  should be consid
22450 65 72 65 64 20 70 61 72 74 20 6f 66 20 74 68 65  ered part of the
22460 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
22470 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69  nterface,.** whi
22480 63 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ch is experiment
22490 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74  al and subject t
224a0 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  o change..*/.int
224b0 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61   sqlite3_overloa
224c0 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74  d_function(sqlit
224d0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
224e0 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20  *zFuncName, int 
224f0 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  nArg);../*.** Th
22500 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
22510 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
22520 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e   mechanism defin
22530 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75  ed above (back u
22540 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e  p.** to a commen
22550 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d  t remarkably sim
22560 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65  ilar to this one
22570 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  ) is currently c
22580 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
22590 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
225a0 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
225b0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
225c0 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
225d0 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
225e0 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
225f0 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
22600 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
22610 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
22620 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
22630 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
22640 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65  m stabilizes, we
22650 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
22660 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
22670 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
22680 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
22690 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
226a0 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a  omment..**.*****
226b0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d  * EXPERIMENTAL -
226c0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
226d0 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63  ge without notic
226e0 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e **************
226f0 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .*/../*.** CAPI3
22700 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f  REF: A Handle To
22710 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a   An Open BLOB.**
22720 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
22730 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
22740 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72   opaque structur
22750 65 20 69 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a  e is used to .**
22760 20 72 65 70 72 65 73 65 6e 74 20 61 6e 20 62 6c   represent an bl
22770 6f 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62 6c  ob-handle.  A bl
22780 6f 62 2d 68 61 6e 64 6c 65 20 69 73 20 63 72 65  ob-handle is cre
22790 61 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  ated by.** [sqli
227a0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
227b0 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62   and destroyed b
227c0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
227d0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  close()]..** The
227e0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
227f0 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
22800 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
22810 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
22820 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
22830 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
22840 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
22850 66 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54  f the blob..** T
22860 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
22870 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
22880 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
22890 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62  size of the.** b
228a0 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  lob in bytes..*/
228b0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
228c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
228d0 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
228e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
228f0 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
22900 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a  emental I/O.**.*
22910 2a 20 4f 70 65 6e 20 61 20 68 61 6e 64 6c 65 20  * Open a handle 
22920 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f 63 61  to the blob loca
22930 74 65 64 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c  ted in row iRow,
22940 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e  , column zColumn
22950 2c 20 0a 2a 2a 20 74 61 62 6c 65 20 7a 54 61 62  , .** table zTab
22960 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a  le in database z
22970 44 62 2e 20 69 2e 65 2e 20 74 68 65 20 73 61 6d  Db. i.e. the sam
22980 65 20 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c  e blob that woul
22990 64 0a 2a 2a 20 62 65 20 73 65 6c 65 63 74 65 64  d.** be selected
229a0 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e   by:.**.** <pre>
229b0 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a  .**     SELECT z
229c0 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e  Column FROM zDb.
229d0 7a 54 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77  zTable WHERE row
229e0 69 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f  id = iRow;.** </
229f0 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  pre>.**.** If th
22a00 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
22a10 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  r is non-zero, t
22a20 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65  he blob is opene
22a30 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61  d for .** read a
22a40 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e  nd write access.
22a50 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20   If it is zero, 
22a60 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e  the blob is open
22a70 65 64 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20  ed for read .** 
22a80 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  access..**.** On
22a90 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
22aa0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
22ab0 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a  d and the new .*
22ac0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
22ad0 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69  | blob handle] i
22ae0 73 20 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70  s written to *pp
22af0 42 6c 6f 62 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  Blob..** Otherwi
22b00 73 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  se an error code
22b10 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
22b20 20 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 77   .** any value w
22b30 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f  ritten to *ppBlo
22b40 62 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  b should not be 
22b50 75 73 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c  used by the call
22b60 65 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  er..** This func
22b70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61  tion sets the da
22b80 74 61 62 61 73 65 2d 68 61 6e 64 6c 65 20 65 72  tabase-handle er
22b90 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
22ba0 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62  sage.** accessib
22bb0 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  le via [sqlite3_
22bc0 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b  errcode()] and [
22bd0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
22be0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
22bf0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73  3_blob_open(.  s
22c00 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74  qlite3*,.  const
22c10 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f   char *zDb,.  co
22c20 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
22c30 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
22c40 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74  zColumn,.  sqlit
22c50 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20  e3_int64 iRow,. 
22c60 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71   int flags,.  sq
22c70 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42  lite3_blob **ppB
22c80 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lob.);../*.** CA
22c90 50 49 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41  PI3REF:  Close A
22ca0 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a   BLOB Handle.**.
22cb0 2a 2a 20 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e  ** Close an open
22cc0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
22cd0 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a   blob handle]..*
22ce0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
22cf0 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  ob_close(sqlite3
22d00 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
22d10 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 74 75   CAPI3REF:  Retu
22d20 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41  rn The Size Of A
22d30 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a  n Open BLOB.**.*
22d40 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
22d50 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68  e in bytes of th
22d60 65 20 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c  e blob accessibl
22d70 65 20 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a  e via the open .
22d80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
22d90 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20   | blob-handle] 
22da0 70 61 73 73 65 64 20 61 73 20 61 6e 20 61 72 67  passed as an arg
22db0 75 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ument..*/.int sq
22dc0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
22dd0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
22de0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22df0 46 3a 20 20 52 65 61 64 20 44 61 74 61 20 46 72  F:  Read Data Fr
22e00 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  om A BLOB Increm
22e10 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68  entally.**.** Th
22e20 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
22e30 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61  sed to read data
22e40 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a   from an open .*
22e50 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
22e60 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69  | blob-handle] i
22e70 6e 74 6f 20 61 20 63 61 6c 6c 65 72 20 73 75 70  nto a caller sup
22e80 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a  plied buffer..**
22e90 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   n bytes of data
22ea0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
22eb0 20 62 75 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f   buffer.** z fro
22ec0 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c  m the open blob,
22ed0 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
22ee0 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
22ef0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53  ** On success, S
22f00 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
22f10 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c  rned. Otherwise,
22f20 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   an .** [SQLITE_
22f30 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65  ERROR | SQLite e
22f40 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e  rror code] or an
22f50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
22f60 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
22f70 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
22f80 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e   returned..*/.in
22f90 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  t sqlite3_blob_r
22fa0 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ead(sqlite3_blob
22fb0 20 2a 2c 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74   *, void *z, int
22fc0 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   n, int iOffset)
22fd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22fe0 46 3a 20 20 57 72 69 74 65 20 44 61 74 61 20 49  F:  Write Data I
22ff0 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65  nto A BLOB Incre
23000 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54  mentally.**.** T
23010 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
23020 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61  used to write da
23030 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20  ta into an open 
23040 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
23050 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d  b | blob-handle]
23060 20 66 72 6f 6d 20 61 20 75 73 65 72 20 73 75 70   from a user sup
23070 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a  plied buffer..**
23080 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   n bytes of data
23090 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d   are copied from
230a0 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 70   the buffer.** p
230b0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 7a 20 69  ointed to by z i
230c0 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f  nto the open blo
230d0 62 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f  b, starting at o
230e0 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a  ffset iOffset..*
230f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
23100 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
23110 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20  -handle] passed 
23120 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
23130 75 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74  ument.** was not
23140 20 6f 70 65 6e 65 64 20 66 6f 72 20 77 72 69 74   opened for writ
23150 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70  ing (the flags p
23160 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
23170 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
23180 5d 0a 2a 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c  ].*** was zero),
23190 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
231a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
231b0 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20  EADONLY]..**.** 
231c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
231d0 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68  y only modify th
231e0 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68  e contents of th
231f0 65 20 62 6c 6f 62 2c 20 69 74 20 69 73 0a 2a 2a  e blob, it is.**
23200 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
23210 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69   increase the si
23220 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 75 73 69  ze of a blob usi
23230 6e 67 20 74 68 69 73 20 41 50 49 2e 20 49 66 0a  ng this API. If.
23240 2a 2a 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  ** offset iOffse
23250 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6e  t is less than n
23260 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
23270 65 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c  end of the blob,
23280 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
23290 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
232a0 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
232b0 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ritten..**.** On
232c0 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45   success, SQLITE
232d0 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
232e0 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a   Otherwise, an .
232f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
23300 20 7c 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20   | SQLite error 
23310 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
23320 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
23330 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72  D | extended err
23340 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
23350 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rned..*/.int sql
23360 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
23370 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
23380 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69  const void *z, i
23390 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65  nt n, int iOffse
233a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
233b0 52 45 46 3a 20 20 56 69 72 74 75 61 6c 20 46 69  REF:  Virtual Fi
233c0 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
233d0 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  s.**.** A virtua
233e0 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46  l filesystem (VF
233f0 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65  S) is an [sqlite
23400 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a  3_vfs] object.**
23410 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65   that SQLite use
23420 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a  s to interact.**
23430 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c   with the underl
23440 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
23450 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69  ystem.  Most bui
23460 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a  lds come with a.
23470 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c  ** single defaul
23480 74 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70  t VFS that is ap
23490 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68  propriate for th
234a0 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
234b0 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61  .** New VFSes ca
234c0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
234d0 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53  and existing VFS
234e0 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69  es can be unregi
234f0 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66  stered..** The f
23500 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61  ollowing interfa
23510 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
23520 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23530 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69  te3_vfs_find() i
23540 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23550 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
23560 56 46 53 20 67 69 76 65 6e 20 69 74 73 0a 2a 2a  VFS given its.**
23570 20 6e 61 6d 65 2e 20 20 4e 61 6d 65 73 20 61 72   name.  Names ar
23580 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65  e case sensitive
23590 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
235a0 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a  o match, a NULL.
235b0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  ** pointer is re
235c0 74 75 72 6e 65 64 2e 20 20 49 66 20 7a 56 66 73  turned.  If zVfs
235d0 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65  Name is NULL the
235e0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 0a 2a  n the default .*
235f0 2a 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65  * VFS is returne
23600 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53  d..**.** New VFS
23610 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  es are registere
23620 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76  d with sqlite3_v
23630 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 20 20  fs_register().  
23640 45 61 63 68 0a 2a 2a 20 6e 65 77 20 56 46 53 20  Each.** new VFS 
23650 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
23660 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
23670 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
23680 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65  set..** The same
23690 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69   VFS can be regi
236a0 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
236b0 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e  times without in
236c0 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65  jury..** To make
236d0 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53   an existing VFS
236e0 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c   into the defaul
236f0 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20  t VFS, register 
23700 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68  it again.** with
23710 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
23720 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20  ag set.  If two 
23730 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20  different VFSes 
23740 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65  with the.** same
23750 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74   name are regist
23760 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69  ered, the behavi
23770 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
23780 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73    If a.** VFS is
23790 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
237a0 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20   a name that is 
237b0 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
237c0 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e   string,.** then
237d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
237e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a   undefined..** .
237f0 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20  ** Unregister a 
23800 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c  VFS with the sql
23810 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
23820 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  ter() interface.
23830 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75  .** If the defau
23840 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69  lt VFS is unregi
23850 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20  stered, another 
23860 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73  VFS is chosen as
23870 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e  .** the default.
23880 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72    The choice for
23890 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20   the new VFS is 
238a0 61 72 62 69 74 72 61 72 79 2e 0a 2a 2f 0a 73 71  arbitrary..*/.sq
238b0 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74  lite3_vfs *sqlit
238c0 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73  e3_vfs_find(cons
238d0 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65  t char *zVfsName
238e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
238f0 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69  fs_register(sqli
23900 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61  te3_vfs*, int ma
23910 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c  keDflt);.int sql
23920 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
23930 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ter(sqlite3_vfs*
23940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23950 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a  EF: Mutexes.**.*
23960 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
23970 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  e uses these rou
23980 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64  tines for thread
23990 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74  .** synchronizat
239a0 69 6f 6e 2e 20 20 54 68 6f 75 67 68 20 74 68 65  ion.  Though the
239b0 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  y are intended f
239c0 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75  or internal.** u
239d0 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f  se by SQLite, co
239e0 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  de that links ag
239f0 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a  ainst SQLite is.
23a00 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  ** permitted to 
23a10 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  use any of these
23a20 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
23a30 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72   The SQLite sour
23a40 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73  ce code contains
23a50 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
23a60 65 6e 74 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66  entations .** of
23a70 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75   these mutex rou
23a80 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f  tines.  An appro
23a90 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74  priate implement
23aa0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65  ation.** is sele
23ab0 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  cted automatical
23ac0 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ly at compile-ti
23ad0 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  me.  The followi
23ae0 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ng.** implementa
23af0 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61  tions are availa
23b00 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ble in the SQLit
23b10 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  e core:.**.** <u
23b20 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  l>.** <li>   SQL
23b30 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a  ITE_MUTEX_OS2.**
23b40 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
23b50 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20  UTEX_PTHREAD.** 
23b60 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
23b70 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20  TEX_W32.** <li> 
23b80 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e    SQLITE_MUTEX_N
23b90 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  OOP.** </ul>.**.
23ba0 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55  ** The SQLITE_MU
23bb0 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65  TEX_NOOP impleme
23bc0 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74  ntation is a set
23bd0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a   of routines .**
23be0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65   that does no re
23bf0 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69  al locking and i
23c00 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
23c10 72 20 75 73 65 20 69 6e 20 0a 2a 2a 20 61 20 73  r use in .** a s
23c20 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61  ingle-threaded a
23c30 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
23c40 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53   SQLITE_MUTEX_OS
23c50 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  2,.** SQLITE_MUT
23c60 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20  EX_PTHREAD, and 
23c70 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32  SQLITE_MUTEX_W32
23c80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
23c90 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69  .** are appropri
23ca0 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 6f  ate for use on o
23cb0 73 2f 32 2c 20 75 6e 69 78 2c 20 61 6e 64 20 77  s/2, unix, and w
23cc0 69 6e 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49  indows..** .** I
23cd0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
23ce0 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  iled with the SQ
23cf0 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45  LITE_MUTEX_APPDE
23d00 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a  F preprocessor.*
23d10 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20  * macro defined 
23d20 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f  (with "-DSQLITE_
23d30 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29  MUTEX_APPDEF=1")
23d40 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a  , then no mutex.
23d50 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
23d60 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69  n is included wi
23d70 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20  th the library. 
23d80 20 54 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e   The.** mutex in
23d90 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
23da0 20 64 65 66 69 6e 65 64 20 68 65 72 65 20 62 65   defined here be
23db0 63 6f 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a  come external.**
23dc0 20 72 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74   references in t
23dd0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
23de0 79 20 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c  y for which impl
23df0 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d  ementations.** m
23e00 75 73 74 20 62 65 20 70 72 6f 76 69 64 65 64 20  ust be provided 
23e10 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
23e20 6f 6e 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69  on.  This facili
23e30 74 79 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20  ty allows an.** 
23e40 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74  application that
23e50 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53   links against S
23e60 51 4c 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65  QLite to provide
23e70 20 69 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a   its own mutex.*
23e80 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
23e90 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20   without having 
23ea0 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  to modify the SQ
23eb0 4c 69 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a  Lite core..**.**
23ec0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
23ed0 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  ex_alloc() routi
23ee0 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e  ne allocates a n
23ef0 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20  ew.** mutex and 
23f00 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
23f10 72 20 74 6f 20 69 74 2e 20 20 49 66 20 69 74 20  r to it.  If it 
23f20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20  returns NULL.** 
23f30 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20  that means that 
23f40 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f  a mutex could no
23f50 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20  t be allocated. 
23f60 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
23f70 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b  unwind its stack
23f80 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65   and return an e
23f90 72 72 6f 72 2e 20 20 54 68 65 20 61 72 67 75 6d  rror.  The argum
23fa0 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
23fb0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
23fc0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  is one of these 
23fd0 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
23fe0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
23ff0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
24000 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e  TEX_FAST.** <li>
24010 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52    SQLITE_MUTEX_R
24020 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  ECURSIVE.** <li>
24030 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
24040 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20  TATIC_MASTER.** 
24050 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
24060 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a  EX_STATIC_MEM.**
24070 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
24080 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a  TEX_STATIC_MEM2.
24090 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
240a0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
240b0 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  G.** <li>  SQLIT
240c0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
240d0 52 55 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  RU.** </ul>.**.*
240e0 2a 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20  * The first two 
240f0 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20  constants cause 
24100 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
24110 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a  loc() to create.
24120 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20  ** a new mutex. 
24130 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69   The new mutex i
24140 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e  s recursive when
24150 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
24160 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73  CURSIVE.** is us
24170 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73  ed but not neces
24180 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53  sarily so when S
24190 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
241a0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65   is used..** The
241b0 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
241c0 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
241d0 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69  eed to make a di
241e0 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
241f0 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  ween SQLITE_MUTE
24200 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20  X_RECURSIVE and 
24210 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
24220 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20  T if it does.** 
24230 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 42 75  not want to.  Bu
24240 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e  t SQLite will on
24250 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63  ly request a rec
24260 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a  ursive mutex in.
24270 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69  ** cases where i
24280 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f  t really needs o
24290 6e 65 2e 20 20 49 66 20 61 20 66 61 73 74 65 72  ne.  If a faster
242a0 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d   non-recursive m
242b0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
242c0 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  tation is availa
242d0 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20  ble on the host 
242e0 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75  platform, the mu
242f0 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a  tex subsystem.**
24300 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75   might return su
24310 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65  ch a mutex in re
24320 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45  sponse to SQLITE
24330 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a  _MUTEX_FAST..**.
24340 2a 2a 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c  ** The other all
24350 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  owed parameters 
24360 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
24370 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65  _alloc() each re
24380 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  turn.** a pointe
24390 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72  r to a static pr
243a0 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e  eexisting mutex.
243b0 20 20 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75    Four static mu
243c0 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  texes are.** use
243d0 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  d by the current
243e0 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
243f0 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  te.  Future vers
24400 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
24410 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69  * may add additi
24420 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65  onal static mute
24430 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74  xes.  Static mut
24440 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74  exes are for int
24450 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
24460 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70  SQLite only.  Ap
24470 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
24480 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78  use SQLite mutex
24490 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65  es should.** use
244a0 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69   only the dynami
244b0 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e  c mutexes return
244c0 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54  ed by SQLITE_MUT
244d0 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51  EX_FAST or.** SQ
244e0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
244f0 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  SIVE..**.** Note
24500 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20   that if one of 
24510 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  the dynamic mute
24520 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51  x parameters (SQ
24530 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a  LITE_MUTEX_FAST.
24540 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54  ** or SQLITE_MUT
24550 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73  EX_RECURSIVE) is
24560 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74   used then sqlit
24570 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
24580 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69  .** returns a di
24590 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e  fferent mutex on
245a0 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 42 75   every call.  Bu
245b0 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63  t for the static
245c0 20 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73   .** mutex types
245d0 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78  , the same mutex
245e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20   is returned on 
245f0 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20  every call that 
24600 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  has.** the same 
24610 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  type number..**.
24620 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
24630 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74  utex_free() rout
24640 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  ine deallocates 
24650 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  a previously.** 
24660 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69  allocated dynami
24670 63 20 6d 75 74 65 78 2e 20 20 53 51 4c 69 74 65  c mutex.  SQLite
24680 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64   is careful to d
24690 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a  eallocate every.
246a0 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ** dynamic mutex
246b0 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74   that it allocat
246c0 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63  es.  The dynamic
246d0 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f   mutexes must no
246e0 74 20 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65 20  t be in .** use 
246f0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65  when they are de
24700 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65  allocated.  Atte
24710 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f  mpting to deallo
24720 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a  cate a static.**
24730 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69   mutex results i
24740 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
24750 76 69 6f 72 2e 20 20 53 51 4c 69 74 65 20 6e 65  vior.  SQLite ne
24760 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a  ver deallocates.
24770 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65  ** a static mute
24780 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  x..**.** The sql
24790 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
247a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
247b0 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69  utex_try() routi
247c0 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74  nes attempt.** t
247d0 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e  o enter a mutex.
247e0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72    If another thr
247f0 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77  ead is already w
24800 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c  ithin the mutex,
24810 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
24820 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62  x_enter() will b
24830 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33  lock and sqlite3
24840 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c  _mutex_try() wil
24850 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  l return.** SQLI
24860 54 45 5f 42 55 53 59 2e 20 20 54 68 65 20 73 71  TE_BUSY.  The sq
24870 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
24880 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
24890 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a  rns SQLITE_OK.**
248a0 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c   upon successful
248b0 20 65 6e 74 72 79 2e 20 20 4d 75 74 65 78 65 73   entry.  Mutexes
248c0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 53   created using S
248d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
248e0 52 53 49 56 45 20 63 61 6e 0a 2a 2a 20 62 65 20  RSIVE can.** be 
248f0 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  entered multiple
24900 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61   times by the sa
24910 6d 65 20 74 68 72 65 61 64 2e 20 20 49 6e 20 73  me thread.  In s
24920 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a  uch cases the,.*
24930 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20  * mutex must be 
24940 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20  exited an equal 
24950 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
24960 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74  before another t
24970 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74  hread.** can ent
24980 65 72 2e 20 20 49 66 20 74 68 65 20 73 61 6d 65  er.  If the same
24990 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f   thread tries to
249a0 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72   enter any other
249b0 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 0a 2a   kind of mutex.*
249c0 2a 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  * more than once
249d0 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
249e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 20 53  s undefined.   S
249f0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
24a00 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68   exhibit.** such
24a10 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73   behavior in its
24a20 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65   own use of mute
24a30 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  xes..**.** Some 
24a40 73 79 73 74 65 6d 73 20 28 65 78 3a 20 77 69 6e  systems (ex: win
24a50 64 6f 77 73 39 35 29 20 64 6f 20 6e 6f 74 20 74  dows95) do not t
24a60 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 6d 70  he operation imp
24a70 6c 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 73  lemented by.** s
24a80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
24a90 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79  ().  On those sy
24aa0 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d  stems, sqlite3_m
24ab0 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 0a  utex_try() will.
24ac0 2a 2a 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ** always return
24ad0 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54   SQLITE_BUSY.  T
24ae0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f  he SQLite core o
24af0 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a  nly ever uses.**
24b00 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
24b10 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d  ry() as an optim
24b20 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20  ization so this 
24b30 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65  is acceptable be
24b40 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  havior..**.** Th
24b50 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
24b60 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20  leave() routine 
24b70 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 68  exits a mutex th
24b80 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  at was.** previo
24b90 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20  usly entered by 
24ba0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
24bb0 20 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a    The behavior.*
24bc0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69  * is undefined i
24bd0 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e  f the mutex is n
24be0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ot currently ent
24bf0 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63  ered by the.** c
24c00 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72  alling thread or
24c10 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
24c20 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51  y allocated.  SQ
24c30 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76  Lite will.** nev
24c40 65 72 20 64 6f 20 65 69 74 68 65 72 2e 0a 2a 2a  er do either..**
24c50 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
24c60 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
24c70 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
24c80 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
24c90 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  )]..*/.sqlite3_m
24ca0 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75  utex *sqlite3_mu
24cb0 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  tex_alloc(int);.
24cc0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74  void sqlite3_mut
24cd0 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f  ex_free(sqlite3_
24ce0 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
24cf0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
24d00 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  r(sqlite3_mutex*
24d10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  );.int sqlite3_m
24d20 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33  utex_try(sqlite3
24d30 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73  _mutex*);.void s
24d40 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
24d50 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ve(sqlite3_mutex
24d60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
24d70 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66  REF: Mutex Verif
24d80 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
24d90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
24da0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61  3_mutex_held() a
24db0 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
24dc0 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69  _notheld() routi
24dd0 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e  nes.** are inten
24de0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ded for use insi
24df0 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74  de assert() stat
24e00 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 53 51 4c  ements.  The SQL
24e10 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65  ite core.** neve
24e20 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  r uses these rou
24e30 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73  tines except ins
24e40 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20  ide an assert() 
24e50 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  and applications
24e60 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20  .** are advised 
24e70 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65  to follow the le
24e80 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20  ad of the core. 
24e90 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a   The core only.*
24ea0 2a 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65  * provides imple
24eb0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74  mentations for t
24ec0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68  hese routines wh
24ed0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
24ee0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51  d.** with the SQ
24ef0 4c 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e  LITE_DEBUG flag.
24f00 20 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78    External mutex
24f10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
24f20 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71  .** are only req
24f30 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65  uired to provide
24f40 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
24f50 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20  if SQLITE_DEBUG 
24f60 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e  is.** defined an
24f70 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e  d if NDEBUG is n
24f80 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ot defined..**.*
24f90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
24fa0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
24fb0 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 78  rue if the mutex
24fc0 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65   in their argume
24fd0 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72  nt.** is held or
24fe0 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65   not held, respe
24ff0 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20  ctively, by the 
25000 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a  calling thread..
25010 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d  **.** The implem
25020 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  entation is not 
25030 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76  required to prov
25040 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66  ided versions of
25050 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e   these.** routin
25060 65 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79  es that actually
25070 20 77 6f 72 6b 2e 0a 2a 2a 20 49 66 20 74 68 65   work..** If the
25080 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25090 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65  does not provide
250a0 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73   working.** vers
250b0 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f  ions of these ro
250c0 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c  utines, it shoul
250d0 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69  d at least provi
250e0 64 65 20 73 74 75 62 73 0a 2a 2a 20 74 68 61 74  de stubs.** that
250f0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
25100 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20  rue so that one 
25110 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75  does not get spu
25120 72 69 6f 75 73 0a 2a 2a 20 61 73 73 65 72 74 69  rious.** asserti
25130 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a  on failures..**.
25140 2a 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65  ** If the argume
25150 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  nt to sqlite3_mu
25160 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61 20  tex_held() is a 
25170 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
25180 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65  n.** the routine
25190 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 31   should return 1
251a0 2e 20 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f  .  This seems co
251b0 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20  unter-intuitive 
251c0 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79  since.** clearly
251d0 20 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f   the mutex canno
251e0 74 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20  t be held if it 
251f0 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20  does not exist. 
25200 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20   But the.** the 
25210 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78  reason the mutex
25220 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
25230 69 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62  is because the b
25240 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75  uild is not.** u
25250 73 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41  sing mutexes.  A
25260 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e  nd we do not wan
25270 74 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63  t the assert() c
25280 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
25290 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
252a0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f  _mutex_held() to
252b0 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d   fail, so a non-
252c0 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a  zero return is.*
252d0 2a 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  * the appropriat
252e0 65 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20  e thing to do.  
252f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
25300 78 5f 6e 6f 74 68 65 6c 64 28 29 20 0a 2a 2a 20  x_notheld() .** 
25310 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64  interface should
25320 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77   also return 1 w
25330 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c  hen given a NULL
25340 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74   pointer..*/.int
25350 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
25360 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  eld(sqlite3_mute
25370 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  x*);.int sqlite3
25380 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73  _mutex_notheld(s
25390 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
253a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
253b0 20 4d 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a   Mutex Types.**.
253c0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
253d0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69  mutex_alloc()] i
253e0 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73 20 61  nterface takes a
253f0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
25400 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65  .** which is one
25410 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
25420 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2f 0a  r constants..*/.
25430 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
25440 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20  UTEX_FAST       
25450 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
25460 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
25470 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a  URSIVE        1.
25480 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
25490 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
254a0 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  ER    2.#define 
254b0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
254c0 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20  TIC_MEM       3 
254d0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   /* sqlite3_mall
254e0 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oc() */.#define 
254f0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
25500 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20  TIC_MEM2      4 
25510 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65   /* sqlite3_rele
25520 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a  ase_memory() */.
25530 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
25540 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
25550 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69        5  /* sqli
25560 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a  te3_random() */.
25570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
25580 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20  UTEX_STATIC_LRU 
25590 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20        6  /* lru 
255a0 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a  page list */../*
255b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
255c0 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20  w-Level Control 
255d0 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65  Of Database File
255e0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
255f0 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
25600 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d  l()] interface m
25610 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61  akes a direct ca
25620 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69  ll to the.** xFi
25630 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
25640 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
25650 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
25660 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a  ject associated.
25670 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ** with a partic
25680 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64  ular database id
25690 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
256a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
256b0 20 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66    The.** name of
256c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
256d0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
256e0 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ed to the databa
256f0 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20  se by the.** <a 
25700 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63  href="lang_attac
25710 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f  h.html">ATTACH</
25720 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74  a> SQL command t
25730 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a  hat opened the.*
25740 2a 20 64 61 74 61 62 61 73 65 2e 20 20 54 6f 20  * database.  To 
25750 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e  control the main
25760 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
25770 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61  use the name "ma
25780 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c  in".** or a NULL
25790 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 74   pointer.  The t
257a0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
257b0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
257c0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72  is routine.** ar
257d0 65 20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c  e passed directl
257e0 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  y through to the
257f0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
25800 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a  d parameters of.
25810 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** the xFileCont
25820 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 54 68 65  rol method.  The
25830 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
25840 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
25850 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f  l.** method beco
25860 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  mes the return v
25870 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75  alue of this rou
25880 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tine..**.** If t
25890 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
258a0 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f  ter (zDbName) do
258b0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65  es not match the
258c0 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20   name of any.** 
258d0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66 69  open database fi
258e0 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  le, then SQLITE_
258f0 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65  ERROR is returne
25900 64 2e 20 20 54 68 69 73 20 65 72 72 6f 72 0a 2a  d.  This error.*
25910 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65  * code is not re
25920 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c  membered and wil
25930 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65  l not be recalle
25940 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72  d by [sqlite3_er
25950 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b  rcode()].** or [
25960 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
25970 5d 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  ].  The underlyi
25980 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ng xFileControl 
25990 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20  method might.** 
259a0 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49  also return SQLI
259b0 54 45 5f 45 52 52 4f 52 2e 20 20 54 68 65 72 65  TE_ERROR.  There
259c0 20 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69   is no way to di
259d0 73 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65  stinguish betwee
259e0 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63  n.** an incorrec
259f0 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e  t zDbName and an
25a00 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65   SQLITE_ERROR re
25a10 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e  turn from the un
25a20 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c  derlying.** xFil
25a30 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e  eControl method.
25a40 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
25a50 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
25a60 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74  OCKSTATE].*/.int
25a70 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
25a80 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20  ntrol(sqlite3*, 
25a90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
25aa0 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  ame, int op, voi
25ab0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f  d*);../*.** Undo
25ac0 20 74 68 65 20 68 61 63 6b 20 74 68 61 74 20 63   the hack that c
25ad0 6f 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 6e 67  onverts floating
25ae0 20 70 6f 69 6e 74 20 74 79 70 65 73 20 74 6f 20   point types to 
25af0 69 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62  integer for.** b
25b00 75 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 73  uilds on process
25b10 6f 72 73 20 77 69 74 68 6f 75 74 20 66 6c 6f 61  ors without floa
25b20 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
25b30 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  rt..*/.#ifdef SQ
25b40 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
25b50 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66  NG_POINT.# undef
25b60 20 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a   double.#endif..
25b70 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
25b80 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20  us.}  /* End of 
25b90 74 68 65 20 27 65 78 74 65 72 6e 20 22 43 22 27  the 'extern "C"'
25ba0 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66   block */.#endif
25bb0 0a 23 65 6e 64 69 66 0a                          .#endif.