/ Hex Artifact Content
Login

Artifact ba55b61cbedad6de6182c51cc8e4546d7a2bbcf9:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 32 35 37 20 32 30 30 37 2f  in,v 1.257 2007/
05f0: 30 39 2f 30 34 20 31 32 3a 30 30 3a 30 30 20 64  09/04 12:00:00 d
0600: 72 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e  rh Exp $.*/.#ifn
0610: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  def _SQLITE3_H_.
0620: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33  #define _SQLITE3
0630: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  _H_.#include <st
0640: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
0650: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
0660: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
0670: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
0680: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
0690: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
06a0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64  rom C++..*/.#ifd
06b0: 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65  ef __cplusplus.e
06c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
06d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
06e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
06f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
0700: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
0710: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
0720: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
0730: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f  extern.#endif../
0740: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 74  *.** Make sure t
0750: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 68 65  hese symbols whe
0760: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
0770: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
0780: 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 2e 0a  header.** file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a  ersion Numbers.*
0840: 2a 0a 2a 2a 20 54 68 65 20 76 65 72 73 69 6f 6e  *.** The version
0850: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
0860: 69 62 72 61 72 79 20 69 73 20 63 6f 6e 74 61 69  ibrary is contai
0870: 6e 65 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  ned in the sqlit
0880: 65 33 2e 68 0a 2a 2a 20 68 65 61 64 65 72 20 66  e3.h.** header f
0890: 69 6c 65 20 69 6e 20 61 20 23 64 65 66 69 6e 65  ile in a #define
08a0: 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 56 45   named SQLITE_VE
08b0: 52 53 49 4f 4e 2e 20 20 54 68 65 20 53 51 4c 49  RSION.  The SQLI
08c0: 54 45 5f 56 45 52 53 49 4f 4e 0a 2a 2a 20 6d 61  TE_VERSION.** ma
08d0: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
08e0: 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  a string constan
08f0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 72  t..**.** The for
0900: 6d 61 74 20 6f 66 20 74 68 65 20 76 65 72 73 69  mat of the versi
0910: 6f 6e 20 73 74 72 69 6e 67 20 69 73 20 22 58 2e  on string is "X.
0920: 59 2e 5a 22 2c 20 77 68 65 72 65 0a 2a 2a 20 58  Y.Z", where.** X
0930: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0940: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 2c 20 59 20  rsion number, Y 
0950: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
0960: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20  sion number and 
0970: 5a 0a 2a 2a 20 69 73 20 74 68 65 20 72 65 6c 65  Z.** is the rele
0980: 61 73 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ase number.  The
0990: 20 58 2e 59 2e 5a 20 6d 69 67 68 74 20 62 65 20   X.Y.Z might be 
09a0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 22 61 6c 70  followed by "alp
09b0: 68 61 22 20 6f 72 20 22 62 65 74 61 22 2e 0a 2a  ha" or "beta"..*
09c0: 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 20 22 33  * For example "3
09d0: 2e 31 2e 31 62 65 74 61 22 2e 0a 2a 2a 0a 2a 2a  .1.1beta"..**.**
09e0: 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73 20   The X value is 
09f0: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69  always 3 in SQLi
0a00: 74 65 2e 20 20 54 68 65 20 58 20 76 61 6c 75 65  te.  The X value
0a10: 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68   only changes wh
0a20: 65 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  en.** backwards 
0a30: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73  compatibility is
0a40: 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69   broken and we i
0a50: 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72 20 62  ntend to never b
0a60: 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77 61 72 64  reak.** backward
0a70: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
0a80: 20 20 54 68 65 20 59 20 76 61 6c 75 65 20 6f 6e    The Y value on
0a90: 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e 0a  ly changes when.
0aa0: 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61 6a  ** there are maj
0ab0: 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61 6e  or feature enhan
0ac0: 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  cements that are
0ad0: 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61 74   forwards compat
0ae0: 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ible.** but not 
0af0: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0b00: 69 62 6c 65 2e 20 20 54 68 65 20 5a 20 76 61 6c  ible.  The Z val
0b10: 75 65 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  ue is incremente
0b20: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0b30: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0b40: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0b50: 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65   Y is incremente
0b60: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
0b70: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0b80: 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ER is an integer
0b90: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0ba0: 0a 2a 2a 20 28 58 2a 31 30 30 30 30 30 30 20 2b  .** (X*1000000 +
0bb0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 2e 20 46 6f   Y*1000 + Z). Fo
0bc0: 72 20 65 78 61 6d 70 6c 65 2c 20 66 6f 72 20 76  r example, for v
0bd0: 65 72 73 69 6f 6e 20 22 33 2e 31 2e 31 62 65 74  ersion "3.1.1bet
0be0: 61 22 2c 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 56  a", .** SQLITE_V
0bf0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 69 73  ERSION_NUMBER is
0c00: 20 73 65 74 20 74 6f 20 33 30 30 31 30 30 31 2e   set to 3001001.
0c10: 20 54 6f 20 64 65 74 65 63 74 20 69 66 20 74 68   To detect if th
0c20: 65 79 20 61 72 65 20 75 73 69 6e 67 20 0a 2a 2a  ey are using .**
0c30: 20 76 65 72 73 69 6f 6e 20 33 2e 31 2e 31 20 6f   version 3.1.1 o
0c40: 72 20 67 72 65 61 74 65 72 20 61 74 20 63 6f 6d  r greater at com
0c50: 70 69 6c 65 20 74 69 6d 65 2c 20 70 72 6f 67 72  pile time, progr
0c60: 61 6d 73 20 6d 61 79 20 75 73 65 20 74 68 65 20  ams may use the 
0c70: 74 65 73 74 20 0a 2a 2a 20 28 53 51 4c 49 54 45  test .** (SQLITE
0c80: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 3e  _VERSION_NUMBER>
0c90: 3d 33 30 30 31 30 30 31 29 2e 0a 2a 2a 0a 2a 2a  =3001001)..**.**
0ca0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
0cb0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
0cc0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c  ] and [sqlite3_l
0cd0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
0ce0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
0cf0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20  SQLITE_VERSION  
0d00: 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d         "--VERS--
0d10: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ".#define SQLITE
0d20: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0d30: 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52  --VERSION-NUMBER
0d40: 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  --../*.** CAPI3R
0d50: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
0d60: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0d70: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  bers.**.** These
0d80: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
0d90: 20 76 61 6c 75 65 73 20 65 71 75 69 76 61 6c 65   values equivale
0da0: 6e 74 20 74 6f 20 74 68 65 20 68 65 61 64 65 72  nt to the header
0db0: 20 63 6f 6e 73 74 61 6e 74 73 0a 2a 2a 20 5b 53   constants.** [S
0dc0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 61  QLITE_VERSION] a
0dd0: 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  nd [SQLITE_VERSI
0de0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 54 68 65  ON_NUMBER].  The
0df0: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
0e00: 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
0e10: 69 6e 65 73 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  ines should only
0e20: 20 62 65 20 64 69 66 66 65 72 65 6e 74 20 66 72   be different fr
0e30: 6f 6d 20 74 68 65 20 68 65 61 64 65 72 20 76 61  om the header va
0e40: 6c 75 65 73 0a 2a 2a 20 69 66 20 79 6f 75 20 63  lues.** if you c
0e50: 6f 6d 70 69 6c 65 20 79 6f 75 72 20 70 72 6f 67  ompile your prog
0e60: 72 61 6d 20 75 73 69 6e 67 20 61 6e 20 73 71 6c  ram using an sql
0e70: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 72  ite3.h header fr
0e80: 6f 6d 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e  om a.** differen
0e90: 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  t version of SQL
0ea0: 69 74 65 20 74 68 61 74 20 74 68 65 20 76 65 72  ite that the ver
0eb0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 6c 69 62 72  sion of the libr
0ec0: 61 72 79 20 79 6f 75 0a 2a 2a 20 6c 69 6e 6b 20  ary you.** link 
0ed0: 61 67 61 69 6e 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  against..**.** T
0ee0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
0ef0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
0f00: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
0f10: 65 20 74 65 78 74 20 6f 66 20 74 68 65 0a 2a 2a  e text of the.**
0f20: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0f30: 5d 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 73  ] string.  The s
0f40: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
0f50: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
0f60: 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 65 72  urns.** a poiner
0f70: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
0f80: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
0f90: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
0fa0: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 70  function.** is p
0fb0: 72 6f 76 69 64 65 64 20 66 6f 72 20 44 4c 4c 20  rovided for DLL 
0fc0: 75 73 65 72 73 20 77 68 6f 20 63 61 6e 20 6f 6e  users who can on
0fd0: 6c 79 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  ly access functi
0fe0: 6f 6e 73 20 61 6e 64 20 6e 6f 74 0a 2a 2a 20 63  ons and not.** c
0ff0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1000: 74 68 65 20 44 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49  the DLL..*/.SQLI
1010: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
1020: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
1030: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
1040: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
1050: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e  ersion(void);.in
1060: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
1070: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
1080: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1090: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
10a0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
10b0: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
10c0: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
10d0: 72 65 74 75 72 6e 73 20 54 52 55 45 20 28 6e 6f  returns TRUE (no
10e0: 6e 7a 65 72 6f 29 20 69 66 20 53 51 4c 69 74 65  nzero) if SQLite
10f0: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1100: 74 68 0a 2a 2a 20 61 6c 6c 20 6f 66 20 69 74 73  th.** all of its
1110: 20 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64   mutexes enabled
1120: 20 61 6e 64 20 69 73 20 74 68 75 73 20 74 68 72   and is thus thr
1130: 65 61 64 73 61 66 65 2e 20 20 49 74 20 72 65 74  eadsafe.  It ret
1140: 75 72 6e 73 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  urns.** zero if 
1150: 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 62  the particular b
1160: 75 69 6c 64 20 69 73 20 66 6f 72 20 73 69 6e 67  uild is for sing
1170: 6c 65 2d 74 68 72 65 61 64 65 64 20 6f 70 65 72  le-threaded oper
1180: 61 74 69 6f 6e 0a 2a 2a 20 6f 6e 6c 79 2e 0a 2a  ation.** only..*
1190: 2a 0a 2a 2a 20 52 65 61 6c 6c 79 20 61 6c 6c 20  *.** Really all 
11a0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 64 6f 65  this routine doe
11b0: 73 20 69 73 20 72 65 74 75 72 6e 20 74 72 75 65  s is return true
11c0: 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63   if SQLite was c
11d0: 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
11e0: 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 54 48 52  the -DSQLITE_THR
11f0: 45 41 44 53 41 46 45 3d 31 20 6f 70 74 69 6f 6e  EADSAFE=1 option
1200: 20 61 6e 64 20 66 61 6c 73 65 20 69 66 0a 2a 2a   and false if.**
1210: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 2d   compiled with -
1220: 44 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  DSQLITE_THREADSA
1230: 46 45 3d 30 2e 20 20 49 66 20 53 51 4c 69 74 65  FE=0.  If SQLite
1240: 20 75 73 65 73 20 61 6e 0a 2a 2a 20 61 70 70 6c   uses an.** appl
1250: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1260: 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 2c  mutex subsystem,
1270: 20 6d 61 6c 6c 6f 63 20 73 75 62 73 79 73 74 65   malloc subsyste
1280: 6d 2c 20 63 6f 6c 6c 61 74 69 6e 67 0a 2a 2a 20  m, collating.** 
1290: 73 65 71 75 65 6e 63 65 2c 20 56 46 53 2c 20 53  sequence, VFS, S
12a0: 51 4c 20 66 75 6e 63 74 69 6f 6e 2c 20 70 72 6f  QL function, pro
12b0: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 2c 20  gress callback, 
12c0: 63 6f 6d 6d 69 74 20 68 6f 6f 6b 2c 0a 2a 2a 20  commit hook,.** 
12d0: 65 78 74 65 6e 73 69 6f 6e 2c 20 6f 72 20 6f 74  extension, or ot
12e0: 68 65 72 20 61 63 63 65 73 73 6f 72 69 65 73 20  her accessories 
12f0: 61 6e 64 20 74 68 65 73 65 20 61 64 64 2d 6f 6e  and these add-on
1300: 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 74 68 72  s are not.** thr
1310: 65 61 64 73 61 66 65 2c 20 74 68 65 6e 20 63 6c  eadsafe, then cl
1320: 65 61 72 6c 79 20 74 68 65 20 63 6f 6d 62 69 6e  early the combin
1330: 61 74 69 6f 6e 20 77 69 6c 6c 20 6e 6f 74 20 62  ation will not b
1340: 65 20 74 68 72 65 61 64 73 61 66 65 0a 2a 2a 20  e threadsafe.** 
1350: 65 69 74 68 65 72 2e 20 20 48 65 6e 63 65 2c 20  either.  Hence, 
1360: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6e 65 76  this routine nev
1370: 65 72 20 72 65 70 6f 72 74 73 20 74 68 61 74 20  er reports that 
1380: 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
1390: 73 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  s guaranteed to 
13a0: 62 65 20 74 68 72 65 61 64 73 61 66 65 2c 20 6f  be threadsafe, o
13b0: 6e 6c 79 20 77 68 65 6e 20 69 74 20 69 73 20 67  nly when it is g
13c0: 75 61 72 61 6e 74 65 65 64 20 6e 6f 74 0a 2a 2a  uaranteed not.**
13d0: 20 74 6f 20 62 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   to be..**.** Th
13e0: 69 73 20 69 73 20 61 6e 20 65 78 70 65 72 69 6d  is is an experim
13f0: 65 6e 74 61 6c 20 41 50 49 20 61 6e 64 20 6d 61  ental API and ma
1400: 79 20 67 6f 20 61 77 61 79 20 6f 72 20 63 68 61  y go away or cha
1410: 6e 67 65 20 69 6e 20 66 75 74 75 72 65 0a 2a 2a  nge in future.**
1420: 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
1430: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
1440: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
1450: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
1460: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1470: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 45 61   Handle.**.** Ea
1480: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
1490: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
14a0: 73 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65  sented by pointe
14b0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14c0: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75   of the.** opaqu
14d0: 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65  e structure name
14e0: 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74  d "sqlite3".  It
14f0: 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68   is useful to th
1500: 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  ink of an sqlite
1510: 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20  3.** pointer as 
1520: 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  an object.  The 
1530: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1540: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1550: 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  6()], and.** [sq
1560: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1570: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
1580: 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  its constructors
1590: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
15a0: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73  _close()] is its
15b0: 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68   destructor.  Th
15c0: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
15d0: 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
15e0: 20 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74   (such as [sqlit
15f0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1600: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
1610: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
1620: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1630: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
1640: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
1650: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
1660: 64 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62  ds on this.** ob
1670: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
1680: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
1690: 73 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a  sqlite3;.../*.**
16a0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
16b0: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a  t Integer Types.
16c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f 6d 70 69  **.** Some compi
16d0: 6c 65 72 73 20 64 6f 20 6e 6f 74 20 73 75 70 70  lers do not supp
16e0: 6f 72 74 20 74 68 65 20 22 6c 6f 6e 67 20 6c 6f  ort the "long lo
16f0: 6e 67 22 20 64 61 74 61 74 79 70 65 2e 20 20 53  ng" datatype.  S
1700: 6f 20 77 65 20 68 61 76 65 0a 2a 2a 20 74 6f 20  o we have.** to 
1710: 64 6f 20 63 6f 6d 70 69 6c 65 72 2d 73 70 65 63  do compiler-spec
1720: 69 66 69 63 20 74 79 70 65 64 65 66 73 20 66 6f  ific typedefs fo
1730: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1740: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1750: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4d 61 6e  egers..**.** Man
1760: 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
1770: 63 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 71  ce functions req
1780: 75 69 72 65 20 61 20 36 34 2d 62 69 74 20 69 6e  uire a 64-bit in
1790: 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 73 2e  teger arguments.
17a0: 0a 2a 2a 20 54 68 6f 73 65 20 69 6e 74 65 72 66  .** Those interf
17b0: 61 63 65 73 20 61 72 65 20 64 65 63 6c 61 72 65  aces are declare
17c0: 64 20 75 73 69 6e 67 20 74 68 69 73 20 74 79 70  d using this typ
17d0: 65 64 65 66 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  edef..*/.#ifdef 
17e0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
17f0: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
1800: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
1810: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1820: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
1830: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
1840: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1850: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
1860: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
1870: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
1880: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
1890: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
18a0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
18b0: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
18c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
18d0: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
18e0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
18f0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
1900: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
1910: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
1920: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
1930: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
1940: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
1950: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
1960: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
1970: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
1980: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
1990: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
19a0: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
19b0: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
19c0: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
19d0: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
19e0: 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65  g-point.*/.#ifde
19f0: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
1a00: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
1a10: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
1a20: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
1a30: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1a40: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
1a50: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1a60: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 68 69 73  .**.** Call this
1a70: 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
1a80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
1a90: 72 75 63 74 75 72 65 20 74 68 61 74 20 77 61 73  ructure that was
1aa0: 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72   previously.** r
1ab0: 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
1ac0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1ad0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ae0: 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
1af0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64  3_open_v2()] and
1b00: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
1b10: 6e 67 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ng database will
1b20: 20 62 79 0a 2a 2a 20 63 6c 6f 73 65 64 2e 0a 2a   by.** closed..*
1b30: 2a 0a 2a 2a 20 41 6c 6c 20 53 51 4c 20 73 74 61  *.** All SQL sta
1b40: 74 65 6d 65 6e 74 73 20 70 72 65 70 61 72 65 64  tements prepared
1b50: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b60: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1b70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1b80: 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6d 75 73  pare16_v2()] mus
1b90: 74 20 62 65 20 64 65 73 74 72 6f 79 65 64 20 75  t be destroyed u
1ba0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1bb0: 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 62 65 66  nalize()].** bef
1bc0: 6f 72 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ore this routine
1bd0: 20 69 73 20 63 61 6c 6c 65 64 2e 20 4f 74 68 65   is called. Othe
1be0: 72 77 69 73 65 2c 20 53 51 4c 49 54 45 5f 42 55  rwise, SQLITE_BU
1bf0: 53 59 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  SY is returned a
1c00: 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  nd the.** databa
1c10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 72 65  se connection re
1c20: 6d 61 69 6e 73 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a  mains open..**.*
1c30: 2a 20 50 61 73 73 69 6e 67 20 74 68 69 73 20 72  * Passing this r
1c40: 6f 75 74 69 6e 65 20 61 20 64 61 74 61 62 61 73  outine a databas
1c50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1c60: 74 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65  t has already be
1c70: 65 6e 0a 2a 2a 20 63 6c 6f 73 65 64 20 72 65 73  en.** closed res
1c80: 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
1c90: 64 20 62 65 68 61 76 69 6f 72 2e 20 20 49 66 20  d behavior.  If 
1ca0: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  other interfaces
1cb0: 20 74 68 61 74 0a 2a 2a 20 72 65 66 65 72 65 6e   that.** referen
1cc0: 63 65 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  ce the same data
1cd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1ce0: 61 72 65 20 70 65 6e 64 69 6e 67 20 28 65 69 74  are pending (eit
1cf0: 68 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 73 61  her in the.** sa
1d00: 6d 65 20 74 68 72 65 61 64 20 6f 72 20 69 6e 20  me thread or in 
1d10: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
1d20: 73 29 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  s) when this rou
1d30: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 0a  tine is called,.
1d40: 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1d50: 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1d60: 64 20 61 6e 64 20 69 73 20 61 6c 6d 6f 73 74 20  d and is almost 
1d70: 63 65 72 74 61 69 6e 6c 79 20 75 6e 64 65 73 69  certainly undesi
1d80: 72 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  rable..*/.int sq
1d90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
1da0: 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  te3 *);../*.** T
1db0: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61  he type for a ca
1dc0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e  llback function.
1dd0: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61  .** This is lega
1de0: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65  cy and deprecate
1df0: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64  d.  It is includ
1e00: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
1e10: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
1e20: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f  ty and is not do
1e30: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70  cumented..*/.typ
1e40: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
1e50: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69  e3_callback)(voi
1e60: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63  d*,int,char**, c
1e70: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  har**);../*.** C
1e80: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65  API3REF: One-Ste
1e90: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f  p Query Executio
1ea0: 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a  n Interface.**.*
1eb0: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1ec0: 20 69 73 20 75 73 65 64 20 74 6f 20 64 6f 20 61   is used to do a
1ed0: 20 6f 6e 65 2d 74 69 6d 65 20 65 76 61 6c 75 61   one-time evalua
1ee0: 74 61 74 69 6f 6e 20 6f 66 20 7a 65 72 6f 0a 2a  tation of zero.*
1ef0: 2a 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74  * or more SQL st
1f00: 61 74 65 6d 65 6e 74 73 2e 20 20 55 54 46 2d 38  atements.  UTF-8
1f10: 20 74 65 78 74 20 6f 66 20 74 68 65 20 53 51 4c   text of the SQL
1f20: 20 73 74 61 74 65 6d 65 6e 74 73 20 74 6f 0a 2a   statements to.*
1f30: 2a 20 62 65 20 65 76 61 6c 75 74 65 64 20 69 73  * be evaluted is
1f40: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
1f50: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1f60: 65 72 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65  er.  The stateme
1f70: 6e 74 73 0a 2a 2a 20 61 72 65 20 70 72 65 70 61  nts.** are prepa
1f80: 72 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75  red one by one u
1f90: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1fa0: 65 70 61 72 65 28 29 5d 2c 20 65 76 61 6c 75 61  epare()], evalua
1fb0: 74 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ted.** using [sq
1fc0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 74  lite3_step()], t
1fd0: 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73  hen destroyed us
1fe0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1ff0: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
2000: 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  If one or more o
2010: 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2020: 65 6e 74 73 20 61 72 65 20 71 75 65 72 69 65 73  ents are queries
2030: 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 61  , then.** the ca
2040: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2050: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2060: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
2070: 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  s.** invoked onc
2080: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f  e for each row o
2090: 66 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75  f the query resu
20a0: 6c 74 2e 20 20 54 68 69 73 20 63 61 6c 6c 62 61  lt.  This callba
20b0: 63 6b 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 72  ck.** should nor
20c0: 6d 61 6c 6c 79 20 72 65 74 75 72 6e 20 30 2e 20  mally return 0. 
20d0: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
20e0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
20f0: 65 72 6f 0a 2a 2a 20 76 61 6c 75 65 20 74 68 65  ero.** value the
2100: 6e 20 74 68 65 20 71 75 65 72 79 20 69 73 20 61  n the query is a
2110: 62 6f 72 74 65 64 2c 20 61 6c 6c 20 73 75 62 73  borted, all subs
2120: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
2130: 6d 65 6e 74 73 0a 2a 2a 20 61 72 65 20 73 6b 69  ments.** are ski
2140: 70 70 65 64 20 61 6e 64 20 74 68 65 20 73 71 6c  pped and the sql
2150: 69 74 65 33 5f 65 78 65 63 28 29 20 66 75 6e 63  ite3_exec() func
2160: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
2170: 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
2180: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  .**.** The 4th p
2190: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 69 73  arameter to this
21a0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 6e   interface is an
21b0: 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
21c0: 65 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 61  er that is.** pa
21d0: 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
21e0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
21f0: 63 74 69 6f 6e 20 61 73 20 69 74 73 20 66 69 72  ction as its fir
2200: 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
2210: 0a 2a 2a 20 54 68 65 20 32 6e 64 20 70 61 72 61  .** The 2nd para
2220: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
2230: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69  lback function i
2240: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
2250: 2a 2a 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  ** columns in th
2260: 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 2e 20  e query result. 
2270: 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
2280: 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
2290: 63 6b 0a 2a 2a 20 69 73 20 61 6e 20 61 72 72 61  ck.** is an arra
22a0: 79 20 6f 66 20 73 74 72 69 6e 67 73 20 68 6f 6c  y of strings hol
22b0: 64 69 6e 67 20 74 68 65 20 76 61 6c 75 65 73 20  ding the values 
22c0: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 0a  for each column.
22d0: 2a 2a 20 61 73 20 65 78 74 72 61 63 74 65 64 20  ** as extracted 
22e0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
22f0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
2300: 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
2310: 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
2320: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
2330: 6f 66 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 62  of strings.** ob
2340: 74 61 69 6e 65 64 20 75 73 69 6e 67 20 5b 73 71  tained using [sq
2350: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2360: 65 28 29 5d 20 61 6e 64 20 68 6f 6c 64 69 6e 67  e()] and holding
2370: 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  .** the names of
2380: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   each column..**
2390: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
23a0: 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
23b0: 20 4e 55 4c 4c 2c 20 65 76 65 6e 20 66 6f 72 20   NULL, even for 
23c0: 71 75 65 72 69 65 73 2e 20 20 41 20 4e 55 4c 4c  queries.  A NULL
23d0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
23e0: 6e 6f 74 20 61 6e 20 65 72 72 6f 72 2e 20 20 49  not an error.  I
23f0: 74 20 6a 75 73 74 20 6d 65 61 6e 73 20 74 68 61  t just means tha
2400: 74 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  t no callback.**
2410: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
2420: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72  ..**.** If an er
2430: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65  ror occurs while
2440: 20 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c   parsing or eval
2450: 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 28  uating the SQL (
2460: 62 75 74 0a 2a 2a 20 6e 6f 74 20 77 68 69 6c 65  but.** not while
2470: 20 65 78 65 63 75 74 69 6e 67 20 74 68 65 20 63   executing the c
2480: 61 6c 6c 62 61 63 6b 29 20 74 68 65 6e 20 61 6e  allback) then an
2490: 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
24a0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
24b0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
24c0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
24d0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
24e0: 6f 63 28 29 5d 20 61 6e 64 0a 2a 2a 20 2a 65 72  oc()] and.** *er
24f0: 72 6d 73 67 20 69 73 20 6d 61 64 65 20 74 6f 20  rmsg is made to 
2500: 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 6d 65  point to that me
2510: 73 73 61 67 65 2e 20 20 54 68 65 20 63 61 6c 6c  ssage.  The call
2520: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ing function.** 
2530: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
2540: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
2550: 65 6d 6f 72 79 20 75 73 69 6e 67 20 5b 73 71 6c  emory using [sql
2560: 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2570: 20 49 66 20 65 72 72 6d 73 67 3d 3d 4e 55 4c 4c   If errmsg==NULL
2580: 2c 20 74 68 65 6e 20 6e 6f 20 65 72 72 6f 72 20  , then no error 
2590: 6d 65 73 73 61 67 65 20 69 73 20 65 76 65 72 20  message is ever 
25a0: 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54  written..**.** T
25b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
25c0: 69 73 20 69 73 20 53 51 4c 49 54 45 5f 4f 4b 20  is is SQLITE_OK 
25d0: 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  if there are no 
25e0: 65 72 72 6f 72 73 20 61 6e 64 0a 2a 2a 20 73 6f  errors and.** so
25f0: 6d 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45  me other [SQLITE
2600: 5f 4f 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64  _OK | return cod
2610: 65 5d 20 69 66 20 74 68 65 72 65 20 69 73 20 61  e] if there is a
2620: 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 20 54 68  n error.  .** Th
2630: 65 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 74  e particular ret
2640: 75 72 6e 20 76 61 6c 75 65 20 64 65 70 65 6e 64  urn value depend
2650: 73 20 6f 6e 20 74 68 65 20 74 79 70 65 20 6f 66  s on the type of
2660: 20 65 72 72 6f 72 2e 20 0a 2a 2a 0a 2a 2f 0a 69   error. .**.*/.i
2670: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
2680: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
2690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26b0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
26c0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26d0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
26e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26f0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
2700: 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69 6e 74  valuted */.  int
2710: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
2720: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
2730: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
2740: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
2750: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
2760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2770: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2780: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
2790: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
27a0: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
27b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
27d0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
27e0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
27f0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2800: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
2810: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a  DS: SQLITE_OK.**
2820: 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20  .** Many SQLite 
2830: 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2840: 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75   an integer resu
2850: 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65  lt code from the
2860: 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 61 62   set shown.** ab
2870: 6f 76 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ove in order to 
2880: 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73  indicates succes
2890: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
28a0: 0a 2a 2a 20 54 68 65 20 72 65 73 75 6c 74 20 63  .** The result c
28b0: 6f 64 65 73 20 61 62 6f 76 65 20 61 72 65 20 74  odes above are t
28c0: 68 65 20 6f 6e 6c 79 20 6f 6e 65 73 20 72 65 74  he only ones ret
28d0: 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
28e0: 69 6e 20 69 74 73 0a 2a 2a 20 64 65 66 61 75 6c  in its.** defaul
28f0: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2e  t configuration.
2900: 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 5b    However, the [
2910: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
2920: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
2930: 0a 2a 2a 20 41 50 49 20 63 61 6e 20 62 65 20 75  .** API can be u
2940: 73 65 64 20 74 6f 20 73 65 74 20 61 20 64 61 74  sed to set a dat
2950: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 6f 69 6e  abase connectoin
2960: 20 74 6f 20 72 65 74 75 72 6e 20 6d 6f 72 65 20   to return more 
2970: 64 65 74 61 69 6c 65 64 0a 2a 2a 20 72 65 73 75  detailed.** resu
2980: 6c 74 20 63 6f 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  lt codes..**.** 
2990: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
29a0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
29b0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29c0: 6f 64 65 73 5d 0a 2a 2a 0a 2a 2f 0a 23 64 65 66  odes].**.*/.#def
29d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
29e0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
29f0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
2a00: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
2a10: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
2a20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2a30: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
2a40: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
2a50: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
2a60: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
2a70: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
2a80: 20 20 20 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53     2   /* NOT US
2a90: 45 44 2e 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67  ED. Internal log
2aa0: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
2ab0: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
2ac0: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
2ad0: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
2ae0: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
2af0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
2b00: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
2b10: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
2b20: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
2b30: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
2b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
2b50: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
2b60: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
2b70: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
2b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b90: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
2ba0: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
2bb0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
2bc0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
2bd0: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
2be0: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
2bf0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
2c00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c10: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
2c20: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
2c30: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
2c40: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
2c50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
2c60: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
2c70: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
2c80: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
2c90: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
2ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
2cb0: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
2cc0: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
2cd0: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
2ce0: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
2cf0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
2d00: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
2d10: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
2d20: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
2d30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2d40: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
2d50: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
2d60: 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20  Table or record 
2d70: 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65  not found */.#de
2d80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
2d90: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
2da0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
2db0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
2dc0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
2dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
2de0: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
2df0: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
2e00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2e10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2e20: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
2e30: 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e  5   /* NOT USED.
2e40: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
2e50: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
2e60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e70: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
2e80: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
2e90: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
2ea0: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
2eb0: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
2ec0: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
2ed0: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
2ee0: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
2ef0: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
2f00: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
2f10: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
2f20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2f30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
2f40: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
2f50: 74 6f 20 63 6f 6e 74 72 61 69 6e 74 20 76 69 6f  to contraint vio
2f60: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
2f70: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
2f80: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
2f90: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
2fa0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2fb0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
2fc0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
2fd0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
2fe0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2ff0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
3000: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
3010: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
3020: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
3030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
3040: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
3050: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
3060: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
3070: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
3080: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
3090: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
30a0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
30b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
30c0: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
30d0: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
30e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
30f0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
3100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3110: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
3120: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
3130: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
3140: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
3150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
3160: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
3170: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
3180: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
3190: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
31a0: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
31b0: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
31c0: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
31d0: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
31e0: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
31f0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
3200: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3210: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
3220: 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  Codes.**.** In i
3230: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
3240: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
3250: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
3260: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69  turn one of 26 i
3270: 6e 74 65 67 65 72 0a 2a 2a 20 72 65 73 75 6c 74  nteger.** result
3280: 20 63 6f 64 65 73 20 64 65 73 63 72 69 62 65 64   codes described
3290: 20 61 74 20 72 65 73 75 6c 74 2d 63 6f 64 65 73   at result-codes
32a0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
32b0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
32c0: 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66   that.** many of
32d0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
32e0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 72  des are too cour
32f0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
3300: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
3310: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
3320: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
3330: 6f 62 6c 65 6d 73 20 61 73 20 75 73 65 72 73 20  oblems as users 
3340: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
3350: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
3360: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
3370: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
3380: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
3390: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
33a0: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
33b0: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
33c0: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
33d0: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
33e0: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
33f0: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
3400: 65 72 72 6f 72 73 2e 20 20 54 68 65 20 65 78 74  errors.  The ext
3410: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
3420: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 28  es are enabled (
3430: 6f 72 20 64 69 73 61 62 6c 65 64 29 20 66 6f 72  or disabled) for
3440: 20 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61   .** each databa
3450: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
3460: 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
3470: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
3480: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
3490: 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f 66  ..** .** Some of
34a0: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65   the available e
34b0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
34c0: 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20  odes are listed 
34d0: 61 62 6f 76 65 2e 0a 2a 2a 20 57 65 20 65 78 70  above..** We exp
34e0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
34f0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
3500: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
3510: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
3520: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
3530: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
3540: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
3550: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
3560: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
3570: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
3580: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
3590: 4c 69 74 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  Lite..** .** The
35a0: 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66   symbolic name f
35b0: 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72  or an extended r
35c0: 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61 79  esult code alway
35d0: 73 20 63 6f 6e 74 61 69 6e 73 20 61 20 72 65 6c  s contains a rel
35e0: 61 74 65 64 0a 2a 2a 20 70 72 69 6d 61 72 79 20  ated.** primary 
35f0: 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61  result code as a
3600: 20 70 72 65 66 69 78 2e 20 20 50 72 69 6d 61 72   prefix.  Primar
3610: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63  y result codes c
3620: 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 0a  ontain a single.
3630: 2a 2a 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  ** "_" character
3640: 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65 73 75  .  Extended resu
3650: 6c 74 20 63 6f 64 65 73 20 63 6f 6e 74 61 69 6e  lt codes contain
3660: 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22   two or more "_"
3670: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
3680: 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  The numeric valu
3690: 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64  e of an extended
36a0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63 61 6e   result code can
36b0: 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
36c0: 20 69 74 73 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   its.** correspo
36d0: 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65  nding primary re
36e0: 73 75 6c 74 20 63 6f 64 65 20 62 79 20 6d 61 73  sult code by mas
36f0: 6b 69 6e 67 20 6f 66 66 20 74 68 65 20 6c 6f 77  king off the low
3700: 65 72 20 38 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a  er 8 bytes..**.*
3710: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
3720: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
3730: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
3740: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
3750: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
3760: 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69  y zero..*/.#defi
3770: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
3780: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 28 53  READ          (S
3790: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
37a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
37b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
37c0: 5f 52 45 41 44 20 20 20 20 28 53 51 4c 49 54 45  _READ    (SQLITE
37d0: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
37e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37f0: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
3800: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3810: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
3820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3830: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
3840: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3850: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
3860: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
3870: 46 53 59 4e 43 20 20 20 20 20 28 53 51 4c 49 54  FSYNC     (SQLIT
3880: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
3890: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
38a0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
38b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
38c0: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
38d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
38e0: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
38f0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3900: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
3910: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
3920: 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  OCK        (SQLI
3930: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
3940: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3950: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
3960: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3970: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
3980: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3990: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
39a0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
39b0: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
39c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
39d0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 28 53 51  LOCKED       (SQ
39e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
39f0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
3a00: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
3a10: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
3a20: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 43 6f 6d 62  tions.**.** Comb
3a30: 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66  ination of the f
3a40: 6f 6c 6c 6f 77 69 6e 67 20 62 69 74 20 76 61 6c  ollowing bit val
3a50: 75 65 73 20 61 72 65 20 75 73 65 64 20 61 73 20  ues are used as 
3a60: 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  the.** third arg
3a70: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
3a80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3a90: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
3aa0: 2a 20 61 73 20 66 6f 75 72 74 68 20 61 72 67 75  * as fourth argu
3ab0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 78 4f 70 65  ment to the xOpe
3ac0: 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a  n method of the.
3ad0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
3ae0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2f 0a 23   object..**.*/.#
3af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3b00: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
3b10: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
3b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3b30: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
3b40: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
3b50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3b60: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
3b70: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
3b80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3b90: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
3ba0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
3bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3bc0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
3bd0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
3be0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3bf0: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
3c00: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
3c10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3c20: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
3c30: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
3c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3c50: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
3c60: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
3c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3c80: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
3c90: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 23      0x00000800.#
3ca0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3cb0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
3cc0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23      0x00001000.#
3cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3ce0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
3cf0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23      0x00002000.#
3d00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3d10: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
3d20: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 0a  L   0x00004000..
3d30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3d40: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
3d50: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65  istics.**.** The
3d60: 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69   xDeviceCapabili
3d70: 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ties method of t
3d80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
3d90: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
3da0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
3db0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
3dc0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 66 6f  vector of the fo
3dd0: 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 62 69 74 20 76  llowing.** bit v
3de0: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
3df0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
3e00: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
3e10: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
3e20: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
3e30: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
3e40: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
3e50: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
3e60: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
3e70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3e80: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
3e90: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
3ea0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
3eb0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
3ec0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
3ed0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
3ee0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
3ef0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
3f00: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
3f10: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
3f20: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
3f30: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
3f40: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
3f50: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
3f60: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
3f70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
3f80: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
3f90: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
3fa0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
3fb0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
3fc0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
3fd0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
3fe0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
3ff0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
4000: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
4010: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
4020: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
4030: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
4040: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
4050: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
4060: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
4070: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
4080: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
4090: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
40a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
40b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
40c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
40d0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
40e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
40f0: 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  2       0x000000
4100: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
4110: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
4120: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4130: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
4140: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
4150: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4160: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
4170: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
4180: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4190: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
41a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
41b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
41c0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
41d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
41e0: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  K       0x000000
41f0: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
4200: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
4210: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  K       0x000000
4220: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
4230: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
4240: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31  K       0x000001
4250: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4260: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
4270: 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32  END     0x000002
4280: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4290: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
42a0: 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34  AL      0x000004
42b0: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
42c0: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
42d0: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51   Levels.**.** SQ
42e0: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
42f0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69   the following i
4300: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
4310: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
4320: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
4330: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
4340: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
4350: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
4360: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
4370: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
4380: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
4390: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
43a0: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
43b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
43c0: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
43d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
43e0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
43f0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
4400: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
4410: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
4420: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
4430: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
4440: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
4450: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
4460: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
4470: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
4480: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
4490: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
44a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
44b0: 2a 2a 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  ** object it use
44c0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
44d0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
44e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
44f0: 61 73 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  as.** the second
4500: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
4510: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
4520: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
4530: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
4540: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
4550: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
4560: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
4570: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
4580: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
4590: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
45a0: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
45b0: 73 68 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  shed.  The SQLIT
45c0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 6d 65  E_SYNC_NORMAL me
45d0: 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 6e  ans .** to use n
45e0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
45f0: 6d 61 6e 74 69 63 73 2e 20 20 54 68 65 20 53 51  mantics.  The SQ
4600: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
4610: 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f  lag means .** to
4620: 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73 74   use Mac OS-X st
4630: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
4640: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
4650: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4660: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
4670: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
4680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
4690: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
46a0: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
46b0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
46c0: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
46d0: 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  0.../*.** CAPI3R
46e0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
46f0: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
4700: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
4710: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
4720: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
4730: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
4740: 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  OS.** interface 
4750: 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69 64 75  layer.  Individu
4760: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  al OS interface 
4770: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
4780: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
4790: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
47a0: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
47b0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
47c0: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
47d0: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
47e0: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
47f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
4800: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
4810: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
4820: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
4830: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
4840: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
4850: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
4860: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
4870: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
4880: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
4890: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
48a0: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
48b0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
48c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
48d0: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
48e0: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
48f0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
4900: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
4910: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
4920: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
4930: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
4940: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
4950: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
4960: 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63  ] xOpen method c
4970: 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69 6e 74 65  ontains a pointe
4980: 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61  r to.** an insta
4990: 6e 63 65 20 6f 66 20 74 68 65 20 74 68 69 73 20  nce of the this 
49a0: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
49b0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
49c0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65 64  .** methods used
49d0: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
49e0: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ous operations a
49f0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
4a00: 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  file..**.** The 
4a10: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
4a20: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
4a30: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
4a40: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
4a50: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
4a60: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
4a70: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
4a80: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 20  rmal fsync()..* 
4a90: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
4aa0: 63 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d 58  ce is an.** OS-X
4ab0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
4ac0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e    The SQLITE_SYN
4ad0: 43 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 79 20  C_DATA flag may 
4ae0: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a 2a 2a  be ORed in to.**
4af0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
4b00: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
4b10: 74 68 65 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74  the file and not
4b20: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
4b30: 20 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 65 64   to be.** synced
4b40: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 6e 74  ..** .** The int
4b50: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
4b60: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
4b70: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
4b80: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
4b90: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
4ba0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
4bb0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
4bc0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
4bd0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
4be0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
4bf0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
4c00: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
4c10: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
4c20: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
4c30: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
4c40: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
4c50: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
4c60: 20 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 20   the lock.  .** 
4c70: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
4c80: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
4c90: 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20  looks.** to see 
4ca0: 69 66 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  if any database 
4cb0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 74 68  connection, eith
4cc0: 65 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20 70 72  er in this.** pr
4cd0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
4ce0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
4cf0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20 52 45  is holding an RE
4d00: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
4d10: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
4d20: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
4d30: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
4d40: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
4d50: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
4d60: 20 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e 0a 2a   false if not..*
4d70: 2a 20 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  * .** The xFileC
4d80: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
4d90: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
4da0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
4db0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
4dc0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
4dd0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
4de0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
4df0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
4e00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
4e10: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
4e20: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
4e30: 6f 70 22 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  op" argument.** 
4e40: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 70  is an integer op
4e50: 63 6f 64 65 2e 20 20 20 54 68 65 20 74 68 69 72  code.   The thir
4e60: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  d.** argument is
4e70: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
4e80: 65 72 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  er which is inte
4e90: 6e 64 65 64 20 74 6f 20 62 65 20 61 20 70 6f 69  nded to be a poi
4ea0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74 72  nter.** to a str
4eb0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
4ec0: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
4ed0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
4ee0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
4ef0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
4f00: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
4f10: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
4f20: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
4f30: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
4f40: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
4f50: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
4f60: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
4f70: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
4f80: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
4f90: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
4fa0: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
4fb0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
4fc0: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
4fd0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
4fe0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
4ff0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
5000: 73 65 72 76 65 73 20 6f 70 63 6f 64 65 73 20 6c  serves opcodes l
5010: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
5020: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 20 0a 2a   its own use. .*
5030: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
5040: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
5050: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
5060: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
5070: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
5080: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
5090: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
50a0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
50b0: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
50c0: 70 63 6f 64 65 73 20 0a 2a 2a 20 67 72 65 61 74  pcodes .** great
50d0: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
50e0: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a  void conflicts..
50f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
5100: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
5110: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
5120: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
5130: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
5140: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
5150: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
5160: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
5170: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
5180: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
5190: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
51a0: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
51b0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
51c0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
51d0: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
51e0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
51f0: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
5200: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
5210: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
5220: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
5230: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
5240: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
5250: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
5260: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5270: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
5280: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
5290: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
52a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
52b0: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
52c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
52d0: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
52e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
52f0: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
5300: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
5310: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
5320: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
5330: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
5340: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5350: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
5360: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
5370: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
5380: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
5390: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
53a0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
53b0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
53c0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
53d0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
53e0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
53f0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
5400: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5410: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
5420: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
5430: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
5440: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
5450: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
5460: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
5470: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
5480: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
5490: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
54a0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
54b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
54c0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
54d0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
54e0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
54f0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
5500: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
5510: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
5520: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
5530: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
5540: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
5550: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
5560: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
5570: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5580: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
5590: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
55a0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
55b0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
55c0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
55d0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
55e0: 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  te()..*/.typedef
55f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
5600: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
5610: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
5620: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
5630: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
5640: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
5650: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
5660: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
5670: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
5680: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
5690: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
56a0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
56b0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
56c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
56d0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
56e0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
56f0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
5700: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
5710: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
5720: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
5730: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
5740: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
5750: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
5760: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
5770: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
5780: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
5790: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
57a0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
57b0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
57c0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
57d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
57e0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
57f0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
5800: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
5810: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
5820: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
5830: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
5840: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
5850: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
5860: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
5870: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
5880: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
5890: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
58a0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
58b0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
58c0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
58d0: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
58e0: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
58f0: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
5900: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
5910: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
5920: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
5930: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
5940: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
5950: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
5960: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5970: 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65 20 5b  ect and to the [
5980: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
5990: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
59a0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
59b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
59c0: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
59d0: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
59e0: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
59f0: 6f 70 63 6f 64 65 20 63 61 73 65 73 20 74 68 65  opcode cases the
5a00: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
5a10: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
5a20: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
5a30: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
5a40: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
5a50: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
5a60: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
5a70: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
5a80: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
5a90: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
5aa0: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
5ab0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
5ac0: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
5ad0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
5ae0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
5af0: 74 6f 2e 20 20 54 68 69 73 20 63 61 70 61 62 69  to.  This capabi
5b00: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
5b10: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
5b20: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
5b30: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
5b40: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
5b50: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  * is defined..*/
5b60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b70: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
5b80: 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20         1../*.** 
5b90: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
5ba0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
5bb0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
5bc0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
5bd0: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
5be0: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
5bf0: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
5c00: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
5c10: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
5c20: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
5c30: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
5c40: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
5c50: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
5c60: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
5c70: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
5c80: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
5c90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
5ca0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
5cb0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
5cc0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
5cd0: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
5ce0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
5cf0: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
5d00: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
5d10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5d20: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
5d30: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
5d40: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
5d50: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
5d60: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
5d70: 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  en the.** SQLite
5d80: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
5d90: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
5da0: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
5db0: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
5dc0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
5dd0: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
5de0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
5df0: 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  em"..**.** The i
5e00: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
5e10: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
5e20: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 66   may be larger f
5e30: 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 76 65 72  or future.** ver
5e40: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
5e50: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
5e60: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
5e70: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f  ded to this.** o
5e80: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69  bject when the i
5e90: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73  Version value is
5ea0: 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a 0a 2a   increased..**.*
5eb0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
5ec0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
5ed0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
5ee0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
5ef0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
5f00: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
5f10: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
5f20: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
5f30: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
5f40: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
5f50: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
5f60: 64 20 76 66 73 20 6d 6f 64 75 6c 65 73 20 61 72  d vfs modules ar
5f70: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
5f80: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
5f90: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
5fa0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
5fb0: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
5fc0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
5fd0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
5fe0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
5ff0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
6000: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
6010: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
6020: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
6030: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
6040: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
6050: 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   list..**.** The
6060: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
6070: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 73 20  the only fields 
6080: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
6090: 66 73 20 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  fs .** structure
60a0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
60b0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
60c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
60d0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
60e0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
60f0: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
6100: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
6110: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
6120: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
6130: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
6140: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
6150: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
6160: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
6170: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
6180: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
6190: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
61a0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
61b0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
61c0: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
61d0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
61e0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
61f0: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
6200: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61   SQLite will gua
6210: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20  rantee that the 
6220: 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67  zFilename string
6230: 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f   passed to.** xO
6240: 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c 6c 20  pen() is a full 
6250: 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65 6e 65  pathname as gene
6260: 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c 50 61  rated by xFullPa
6270: 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20  thname() and.** 
6280: 74 68 61 74 20 74 68 65 20 73 74 72 69 6e 67 20  that the string 
6290: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
62a0: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
62b0: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
62c0: 20 63 61 6c 6c 65 64 2e 20 20 53 6f 20 74 68 65   called.  So the
62d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
62e0: 63 61 6e 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  can store a poin
62f0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
6300: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
6310: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
6320: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
6330: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a  some reason..**.
6340: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
6350: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
6360: 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
6370: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
6380: 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
6390: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 49 66 20  open_v2()].  If 
63a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
63b0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
63c0: 6e 31 36 28 29 5d 0a 2a 2a 20 69 73 20 75 73 65  n16()].** is use
63d0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 73  d, then flags is
63e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
63f0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
6400: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
6410: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
6420: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
6430: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
6440: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
6450: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
6460: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
6470: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
6480: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
6490: 79 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20  y be.** set..** 
64a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
64b0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
64c0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
64d0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
64e0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
64f0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
6500: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
6510: 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
6520: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
6530: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
6540: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
6550: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
6560: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
6570: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
6580: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
6590: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
65a0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
65b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
65c0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
65d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
65e0: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
65f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
6600: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
6610: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
6620: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
6630: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
6640: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
6650: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
6660: 68 61 6e 67 65 73 20 74 68 65 20 77 61 79 20 69  hanges the way i
6670: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
6680: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
6690: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
66a0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
66b0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
66c0: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
66d0: 6f 6c 6c 62 61 63 6b 2c 20 6d 69 67 68 74 20 6d  ollback, might m
66e0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
66f0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
6700: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
6710: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
6720: 61 6c 20 61 72 65 0a 2a 2a 20 61 6c 73 6f 20 61  al are.** also a
6730: 20 6e 6f 2d 6f 70 2e 20 20 41 6e 79 20 61 74 74   no-op.  Any att
6740: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
6750: 20 6a 6f 75 72 6e 61 6c 20 72 65 74 75 72 6e 20   journal return 
6760: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 0a 2a 2a  SQLITE_IOERR..**
6770: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
6780: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
6790: 6f 67 6e 69 7a 65 20 74 68 65 20 61 20 64 61 74  ognize the a dat
67a0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 0a  abase file will.
67b0: 2a 2a 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ** be doing page
67c0: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
67d0: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
67e0: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 20 6f 72 64   in a random ord
67f0: 65 72 0a 2a 2a 20 61 6e 64 20 73 65 74 20 75 70  er.** and set up
6800: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
6810: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
6820: 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  ** .** SQLite mi
6830: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
6840: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
6850: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
6860: 4f 70 65 6e 0a 2a 2a 20 6d 65 74 68 6f 64 3a 0a  Open.** method:.
6870: 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ** .** <ul>.** <
6880: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
6890: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
68a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
68b0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
68c0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
68d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
68e0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
68f0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
6900: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
6910: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
6920: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 69   is closed.  Thi
6930: 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65  s will always be
6940: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 0a 2a   set for TEMP .*
6950: 2a 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  * databases and 
6960: 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72  journals and for
6970: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 20 20 54   subjournals.  T
6980: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
6990: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
69a0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
69b0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
69c0: 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ned.** for exclu
69d0: 73 69 76 65 20 61 63 63 65 73 73 2e 20 20 54 68  sive access.  Th
69e0: 69 73 20 66 6c 61 67 20 69 73 20 73 65 74 20 66  is flag is set f
69f0: 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63  or all files exc
6a00: 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ept.** for the m
6a10: 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
6a20: 65 2e 0a 2a 2a 20 0a 2a 2a 20 53 70 61 63 65 20  e..** .** Space 
6a30: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
6a40: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
6a50: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
6a60: 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 61 72  the third .** ar
6a70: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 20  gument to xOpen 
6a80: 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  is allocated by 
6a90: 63 61 6c 6c 65 72 20 28 74 68 65 20 53 51 4c 69  caller (the SQLi
6aa0: 74 65 20 63 6f 72 65 29 2e 20 0a 2a 2a 20 73 7a  te core). .** sz
6ab0: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 61 72 65  OsFile bytes are
6ac0: 20 61 6c 6c 6f 63 61 74 65 64 20 66 6f 72 20 74   allocated for t
6ad0: 68 69 73 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  his object.  The
6ae0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 0a 2a 2a   xOpen method.**
6af0: 20 66 69 6c 6c 73 20 69 6e 20 74 68 65 20 61 6c   fills in the al
6b00: 6c 6f 63 61 74 65 64 20 73 70 61 63 65 2e 0a 2a  located space..*
6b10: 2a 20 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  * .** The flags 
6b20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
6b30: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
6b40: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
6b50: 54 53 5d 20 0a 2a 2a 20 74 6f 20 74 65 73 74 20  TS] .** to test 
6b60: 66 6f 72 20 74 68 65 20 65 78 69 73 74 61 6e 63  for the existanc
6b70: 65 20 6f 66 20 61 20 66 69 6c 65 2c 0a 2a 2a 20  e of a file,.** 
6b80: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
6b90: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 20  S_READWRITE] to 
6ba0: 74 65 73 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69  test to see.** i
6bb0: 66 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  f a file is read
6bc0: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
6bd0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
6be0: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
6bf0: 20 74 65 73 74 20 74 6f 20 73 65 65 20 69 66 20   test to see if 
6c00: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
6c10: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  st readable.  Th
6c20: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 20  e file can be a 
6c30: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
6c40: 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  * .** SQLite wil
6c50: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
6c60: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
6c70: 68 6e 61 6d 65 2b 31 20 62 79 74 65 20 66 6f 72  hname+1 byte for
6c80: 0a 2a 2a 20 74 68 65 20 6f 75 74 70 75 74 20 62  .** the output b
6c90: 75 66 66 65 72 73 20 66 6f 72 20 78 47 65 74 54  uffers for xGetT
6ca0: 65 6d 70 4e 61 6d 65 20 61 6e 64 20 78 46 75 6c  empName and xFul
6cb0: 6c 50 61 74 68 6e 61 6d 65 2e 0a 2a 2a 20 0a 2a  lPathname..** .*
6cc0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
6cd0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
6ce0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
6cf0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
6d00: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
6d10: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
6d20: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
6d30: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
6d40: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
6d50: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
6d60: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
6d70: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
6d80: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
6d90: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
6da0: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
6db0: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
6dc0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
6dd0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
6de0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
6df0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
6e00: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
6e10: 73 73 20 6f 62 74 61 69 6e 65 64 2e 20 20 54 68  ss obtained.  Th
6e20: 65 0a 2a 2a 20 78 53 6c 65 65 70 28 29 20 6d 65  e.** xSleep() me
6e30: 74 68 6f 64 20 63 61 75 73 65 20 74 68 65 20 63  thod cause the c
6e40: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
6e50: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
6e60: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
6e70: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
6e80: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
6e90: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
6ea0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
6eb0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
6ec0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
6ed0: 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a 2a 20 74  nt date and.** t
6ee0: 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ime..*/.typedef 
6ef0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
6f00: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
6f10: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
6f20: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
6f30: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
6f40: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
6f50: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  sion number */. 
6f60: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
6f70: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
6f80: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
6f90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
6fa0: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
6fb0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
6fc0: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
6fd0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
6fe0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
6ff0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
7000: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
7010: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
7020: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
7030: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
7040: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
7050: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
7060: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
7070: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
7080: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
7090: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
70a0: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
70b0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
70c0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
70d0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
70e0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
70f0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
7100: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
7110: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
7120: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
7130: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
7140: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
7150: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
7160: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
7170: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
7180: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 54  );.  int (*xGetT
7190: 65 6d 70 4e 61 6d 65 29 28 73 71 6c 69 74 65 33  empName)(sqlite3
71a0: 5f 76 66 73 2a 2c 20 63 68 61 72 20 2a 7a 4f 75  _vfs*, char *zOu
71b0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
71c0: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
71d0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
71e0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 63 68 61 72  har *zName, char
71f0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
7200: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
7210: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7220: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
7230: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
7240: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
7250: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
7260: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
7270: 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28  void *(*xDlSym)(
7280: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
7290: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
72a0: 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64  zSymbol);.  void
72b0: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
72c0: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
72d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
72e0: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
72f0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
7300: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
7310: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
7320: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
7330: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
7340: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
7350: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
7360: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 2f  *, double*);.  /
7370: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
7380: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
7390: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
73a0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
73b0: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
73c0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
73d0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
73e0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
73f0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
7400: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
7410: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
7420: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
7430: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
7440: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
7450: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
7460: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
7470: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
7480: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
7490: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
74a0: 20 74 68 65 20 6b 69 6e 64 20 6f 66 20 77 68 61   the kind of wha
74b0: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
74c0: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
74d0: 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20 6c  s method is.** l
74e0: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 57 69 74  ooking for.  Wit
74f0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
7500: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
7510: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
7520: 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f 20 73  mply checks to s
7530: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 65  ee if the file e
7540: 78 69 73 74 73 2e 20 20 57 69 74 68 20 53 51 4c  xists.  With SQL
7550: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
7560: 52 49 54 45 2c 0a 2a 2a 20 74 68 65 20 78 41 63  RITE,.** the xAc
7570: 63 65 73 73 20 6d 65 74 68 6f 64 20 63 68 65 63  cess method chec
7580: 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65  ks to see if the
7590: 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65   file is both re
75a0: 61 64 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 77 72  adable.** and wr
75b0: 69 74 61 62 6c 65 2e 20 20 57 69 74 68 20 53 51  itable.  With SQ
75c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
75d0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
75e0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 74 6f  hod.** checks to
75f0: 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65   see if the file
7600: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f   is readable..*/
7610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7620: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
7630: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
7640: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
7650: 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  TE 1.#define SQL
7660: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
7670: 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41       2../*.** CA
7680: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
7690: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
76a0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
76b0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
76c0: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
76d0: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53  sables the.** [S
76e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
76f0: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
7700: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
7710: 65 2e 0a 2a 2a 20 42 79 20 64 65 66 61 75 6c 74  e..** By default
7720: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
7730: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
7740: 20 6f 66 20 6f 6e 6c 79 20 32 36 20 69 6e 74 65   of only 26 inte
7750: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
7760: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
7770: 5d 2e 20 20 57 68 65 6e 20 65 78 74 65 6e 64 65  ].  When extende
7780: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 0a 2a  d result codes.*
7790: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  * are enabled by
77a0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
77b0: 68 65 20 72 65 70 65 74 6f 69 72 65 20 6f 66 20  he repetoire of 
77c0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63 61 6e  result codes can
77d0: 20 62 65 0a 2a 2a 20 6d 75 63 68 20 6c 61 72 67   be.** much larg
77e0: 65 72 20 61 6e 64 20 63 61 6e 20 28 68 6f 70 65  er and can (hope
77f0: 66 75 6c 6c 79 29 20 70 72 6f 76 69 64 65 20 6d  fully) provide m
7800: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
7810: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
7820: 74 20 74 68 65 20 63 61 75 73 65 20 6f 66 20 61  t the cause of a
7830: 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  n error..**.** T
7840: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
7850: 6e 74 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  nt is a boolean 
7860: 76 61 6c 75 65 20 74 68 61 74 20 74 75 72 6e 73  value that turns
7870: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
7880: 0a 2a 2a 20 63 6f 64 65 73 20 6f 6e 20 61 6e 64  .** codes on and
7890: 20 6f 66 66 2e 20 20 45 78 74 65 6e 64 65 64 20   off.  Extended 
78a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
78b0: 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 20   off by default 
78c0: 66 6f 72 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  for.** backwards
78d0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
78e0: 69 74 68 20 6f 6c 64 65 72 20 76 65 72 73 69 6f  ith older versio
78f0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
7900: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
7910: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
7920: 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
7930: 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
7940: 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
7950: 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
7960: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20  * Each entry in 
7970: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
7980: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
7990: 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
79a0: 65 72 20 6b 65 79 0a 2a 2a 20 63 61 6c 6c 65 64  er key.** called
79b0: 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68   the "rowid". Th
79c0: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
79d0: 73 20 61 76 61 69 6c 61 62 6c 65 20 61 73 20 61  s available as a
79e0: 6e 20 75 6e 64 65 63 6c 61 72 65 64 0a 2a 2a 20  n undeclared.** 
79f0: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
7a00: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
7a10: 49 44 5f 2e 20 20 49 66 20 74 68 65 20 74 61 62  ID_.  If the tab
7a20: 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
7a30: 6f 66 0a 2a 2a 20 74 79 70 65 20 49 4e 54 45 47  of.** type INTEG
7a40: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
7a50: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20  hen that column 
7a60: 69 73 20 61 6e 6f 74 68 65 72 20 61 6e 20 61 6c  is another an al
7a70: 69 61 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 72  ias for the.** r
7a80: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  owid..**.** This
7a90: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
7aa0: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
7ab0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
7ac0: 53 45 52 54 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  SERT into.** the
7ad0: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
7ae0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
7af0: 65 63 74 69 6f 6e 20 67 69 76 65 6e 20 69 6e 20  ection given in 
7b00: 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 61 72  the first .** ar
7b10: 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 69  gument.  If no i
7b20: 6e 73 65 72 74 73 20 68 61 76 65 20 65 76 65 72  nserts have ever
7b30: 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 69   occurred on thi
7b40: 73 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  s database.** co
7b50: 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
7b60: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
7b70: 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f  * If an INSERT o
7b80: 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
7b90: 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65  rigger, then the
7ba0: 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0a 2a 2a   rowid of the.**
7bb0: 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 69 73   inserted row is
7bc0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
7bd0: 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e  s routine as lon
7be0: 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
7bf0: 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  .** is running. 
7c00: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
7c10: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73  igger terminates
7c20: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
7c30: 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20  rned.** by this 
7c40: 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
7c50: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75  to the last valu
7c60: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72  e inserted befor
7c70: 65 20 74 68 65 0a 2a 2a 20 74 72 69 67 67 65 72  e the.** trigger
7c80: 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66   fired..**.** If
7c90: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
7ca0: 64 6f 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72  does a new inser
7cb0: 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  t on the same da
7cc0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7cd0: 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20  n.** while this 
7ce0: 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
7cf0: 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
7d00: 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
7d10: 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 74 68  ert rowid,.** th
7d20: 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
7d30: 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74  lue of this rout
7d40: 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
7d50: 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
7d60: 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
7d70: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
7d80: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
7d90: 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
7da0: 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
7db0: 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
7dc0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
7dd0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
7de0: 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
7df0: 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61  ws that were cha
7e00: 6e 67 65 64 0a 2a 2a 20 28 6f 72 20 69 6e 73 65  nged.** (or inse
7e10: 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 29  rted or deleted)
7e20: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
7e30: 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ent SQL statemen
7e40: 74 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e  t.  Only.** chan
7e50: 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
7e60: 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
7e70: 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
7e80: 50 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c  PDATE, or.** DEL
7e90: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
7ea0: 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
7eb0: 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
7ec0: 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
7ed0: 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ers are not coun
7ee0: 74 65 64 2e 20 20 55 73 65 20 74 68 65 20 5b 73  ted.  Use the [s
7ef0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
7f00: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
7f10: 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .** to find the 
7f20: 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
7f30: 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e  changes includin
7f40: 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
7f50: 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a   by triggers..**
7f60: 0a 2a 2a 20 57 69 74 68 69 6e 20 74 68 65 20 62  .** Within the b
7f70: 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
7f80: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  , the sqlite3_ch
7f90: 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
7fa0: 65 20 63 61 6e 20 62 65 0a 2a 2a 20 63 61 6c 6c  e can be.** call
7fb0: 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
7fc0: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
7fd0: 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
7fe0: 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
7ff0: 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
8000: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
8010: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
8020: 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
8030: 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
8040: 41 6c 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20  All changes are 
8050: 63 6f 75 6e 74 65 64 2c 20 65 76 65 6e 20 69 66  counted, even if
8060: 20 74 68 65 79 20 77 65 72 65 20 6c 61 74 65 72   they were later
8070: 20 75 6e 64 6f 6e 65 20 62 79 20 61 0a 2a 2a 20   undone by a.** 
8080: 52 4f 4c 4c 42 41 43 4b 20 6f 72 20 41 42 4f 52  ROLLBACK or ABOR
8090: 54 2e 20 20 45 78 63 65 70 74 2c 20 63 68 61 6e  T.  Except, chan
80a0: 67 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  ges associated w
80b0: 69 74 68 20 63 72 65 61 74 69 6e 67 20 61 6e 64  ith creating and
80c0: 0a 2a 2a 20 64 72 6f 70 70 69 6e 67 20 74 61 62  .** dropping tab
80d0: 6c 65 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  les are not coun
80e0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  ted..**.** If a 
80f0: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 6b 65 73  callback invokes
8100: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
8110: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
8120: 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
8130: 79 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  y,.** then the c
8140: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 69 6e  hanges in the in
8150: 6e 65 72 2c 20 72 65 63 75 72 73 69 76 65 20 63  ner, recursive c
8160: 61 6c 6c 20 61 72 65 20 63 6f 75 6e 74 65 64 20  all are counted 
8170: 74 6f 67 65 74 68 65 72 0a 2a 2a 20 77 69 74 68  together.** with
8180: 20 74 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20   the changes in 
8190: 74 68 65 20 6f 75 74 65 72 20 63 61 6c 6c 2e 0a  the outer call..
81a0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
81b0: 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d  lements the comm
81c0: 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  and "DELETE FROM
81d0: 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20   table" without 
81e0: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a  a WHERE clause.*
81f0: 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e  * by dropping an
8200: 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65  d recreating the
8210: 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69   table.  (This i
8220: 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68  s much faster th
8230: 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f  an going.** thro
8240: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
8250: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
8260: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61  ents from the ta
8270: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
8280: 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69  f.** this optimi
8290: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e  zation, the chan
82a0: 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45  ge count for "DE
82b0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
82c0: 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f   will be.** zero
82d0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
82e0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
82f0: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
8300: 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68  originally in th
8310: 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67  e.** table. To g
8320: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
8330: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
8340: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
8350: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
8360: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
8370: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a  ERE 1" instead..
8380: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
8390: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
83a0: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
83b0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
83c0: 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74  ction.** while t
83d0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
83e0: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
83f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
8400: 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
8410: 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
8420: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
8430: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
8440: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8450: 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
8460: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
8470: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
8480: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
8490: 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
84a0: 73 65 20 72 6f 77 73 20 74 68 61 74 20 68 61 76  se rows that hav
84b0: 65 20 62 65 65 6e 0a 2a 2a 20 6d 6f 64 69 66 69  e been.** modifi
84c0: 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50  ed by INSERT, UP
84d0: 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
84e0: 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
84f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  the database han
8500: 64 6c 65 0a 2a 2a 20 77 61 73 20 6f 70 65 6e 65  dle.** was opene
8510: 64 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  d. This includes
8520: 20 55 50 44 41 54 45 2c 20 49 4e 53 45 52 54 20   UPDATE, INSERT 
8530: 61 6e 64 20 44 45 4c 45 54 45 20 73 74 61 74 65  and DELETE state
8540: 6d 65 6e 74 73 20 65 78 65 63 75 74 65 64 0a 2a  ments executed.*
8550: 2a 20 61 73 20 70 61 72 74 20 6f 66 20 74 72 69  * as part of tri
8560: 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 41  gger programs. A
8570: 6c 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  ll changes are c
8580: 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  ounted as soon a
8590: 73 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  s the.** stateme
85a0: 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
85b0: 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
85c0: 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
85d0: 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 0a 2a 2a  ent handle is.**
85e0: 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
85f0: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
8600: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
8610: 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
8620: 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
8630: 65 33 5f 63 68 61 6e 67 65 28 29 5d 20 69 6e 74  e3_change()] int
8640: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 53 51  erface..**.** SQ
8650: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
8660: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
8670: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
8680: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
8690: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
86a0: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
86b0: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
86c0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
86d0: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
86e0: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
86f0: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
8700: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72  ual elements for
8710: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
8720: 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69  ecause of.** thi
8730: 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  s optimization, 
8740: 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74  the change count
8750: 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f   for "DELETE FRO
8760: 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65  M table" will be
8770: 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c  .** zero regardl
8780: 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ess of the numbe
8790: 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68  r of elements th
87a0: 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c  at were original
87b0: 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62  ly in the.** tab
87c0: 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63  le. To get an ac
87d0: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
87e0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
87f0: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
8800: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
8810: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
8820: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  nstead..**.** If
8830: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
8840: 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
8850: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
8860: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
8870: 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
8880: 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ine is running t
8890: 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
88a0: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75  alue of this rou
88b0: 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  tine.** is undef
88c0: 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
88d0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
88e0: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
88f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
8900: 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
8910: 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
8920: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
8930: 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
8940: 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
8950: 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
8960: 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
8970: 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
8980: 70 70 6f 72 74 75 6e 69 74 79 2e 20 20 54 68 69  pportunity.  Thi
8990: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
89a0: 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
89b0: 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
89c0: 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
89d0: 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
89e0: 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
89f0: 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
8a00: 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
8a10: 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
8a20: 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
8a30: 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  diately..**.** I
8a40: 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
8a50: 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
8a60: 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
8a70: 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
8a80: 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
8a90: 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
8aa0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
8ab0: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
8ac0: 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
8ad0: 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
8ae0: 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 64  routine with a d
8af0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8b00: 6f 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  on that.** is cl
8b10: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
8b20: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
8b30: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
8b40: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  eturns..**.** Th
8b50: 65 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  e SQL operation 
8b60: 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
8b70: 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
8b80: 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
8b90: 54 5d 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  T]..** If an int
8ba0: 65 72 72 75 70 74 65 64 20 6f 70 65 72 61 74 69  errupted operati
8bb0: 6f 6e 20 77 61 73 20 61 6e 20 75 70 64 61 74 65  on was an update
8bc0: 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
8bd0: 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
8be0: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
8bf0: 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
8c00: 73 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  saction will be 
8c10: 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 61  rolled.** back a
8c20: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2f  utomatically..*/
8c30: 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
8c40: 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
8c50: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
8c60: 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
8c70: 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
8c80: 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
8c90: 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
8ca0: 6f 6e 73 20 72 65 74 75 72 6e 20 74 72 75 65 20  ons return true 
8cb0: 69 66 20 74 68 65 20 67 69 76 65 6e 20 69 6e 70  if the given inp
8cc0: 75 74 20 73 74 72 69 6e 67 20 63 6f 6d 70 72 69  ut string compri
8cd0: 73 65 73 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ses.** one or mo
8ce0: 72 65 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20  re complete SQL 
8cf0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 46 6f 72 20  statements. For 
8d00: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  the sqlite3_comp
8d10: 6c 65 74 65 28 29 20 63 61 6c 6c 2c 0a 2a 2a 20  lete() call,.** 
8d20: 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 75  the parameter mu
8d30: 73 74 20 62 65 20 61 20 6e 75 6c 2d 74 65 72 6d  st be a nul-term
8d40: 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
8d50: 69 6e 67 2e 20 46 6f 72 0a 2a 2a 20 73 71 6c 69  ing. For.** sqli
8d60: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
8d70: 2c 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  , a nul-terminat
8d80: 65 64 20 6d 61 63 68 69 6e 65 20 62 79 74 65 20  ed machine byte 
8d90: 6f 72 64 65 72 20 55 54 46 2d 31 36 20 73 74 72  order UTF-16 str
8da0: 69 6e 67 0a 2a 2a 20 69 73 20 72 65 71 75 69 72  ing.** is requir
8db0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
8dc0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
8dd0: 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d  ful for command-
8de0: 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
8df0: 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
8e00: 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
8e10: 72 65 64 20 74 65 78 74 20 66 6f 72 6d 73 20 6f  red text forms o
8e20: 6e 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c  ne or more compl
8e30: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
8e40: 74 73 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  ts or.** if addi
8e50: 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
8e60: 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
8e70: 6e 64 69 6e 67 20 74 68 65 20 73 74 61 74 65 6d  nding the statem
8e80: 65 6e 74 73 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  ents into.** SQL
8e90: 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
8ea0: 20 54 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69   The algorithm i
8eb0: 73 20 73 69 6d 70 6c 65 2e 20 20 49 66 20 74 68  s simple.  If th
8ec0: 65 20 0a 2a 2a 20 6c 61 73 74 20 74 6f 6b 65 6e  e .** last token
8ed0: 20 6f 74 68 65 72 20 74 68 61 6e 20 73 70 61 63   other than spac
8ee0: 65 73 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  es and comments 
8ef0: 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2c 20  is a semicolon, 
8f00: 74 68 65 6e 20 72 65 74 75 72 6e 20 0a 2a 2a 20  then return .** 
8f10: 74 72 75 65 2e 20 20 41 63 74 75 61 6c 6c 79 2c  true.  Actually,
8f20: 20 74 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69   the algorithm i
8f30: 73 20 61 20 6c 69 74 74 6c 65 20 6d 6f 72 65 20  s a little more 
8f40: 63 6f 6d 70 6c 69 63 61 74 65 64 20 74 68 61 6e  complicated than
8f50: 20 74 68 61 74 0a 2a 2a 20 69 6e 20 6f 72 64 65   that.** in orde
8f60: 72 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 74  r to deal with t
8f70: 72 69 67 67 65 72 73 2c 20 62 75 74 20 74 68 65  riggers, but the
8f80: 20 62 61 73 69 63 20 69 64 65 61 20 69 73 20 74   basic idea is t
8f90: 68 65 20 73 61 6d 65 3a 20 20 74 68 65 0a 2a 2a  he same:  the.**
8fa0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
8fb0: 74 20 63 6f 6d 70 6c 65 74 65 20 75 6e 6c 65 73  t complete unles
8fc0: 73 20 69 74 20 65 6e 64 73 20 69 6e 20 61 20 73  s it ends in a s
8fd0: 65 6d 69 63 6f 6c 6f 6e 2e 0a 2a 2f 0a 69 6e 74  emicolon..*/.int
8fe0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
8ff0: 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
9000: 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
9010: 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
9020: 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
9030: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
9040: 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
9050: 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
9060: 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
9070: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
9080: 65 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 63  e identifies a c
9090: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
90a0: 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
90b0: 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76  nvoked.** whenev
90c0: 65 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  er an attempt is
90d0: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
90e0: 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a  database table .
90f0: 2a 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  ** that another 
9100: 74 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73  thread or proces
9110: 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
9120: 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
9130: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
9140: 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
9150: 5d 0a 2a 2a 20 28 6f 72 20 73 6f 6d 65 74 69 6d  ].** (or sometim
9160: 65 73 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  es [SQLITE_IOERR
9170: 5f 42 4c 4f 43 4b 45 44 5d 29 0a 2a 2a 20 69 73  _BLOCKED]).** is
9180: 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
9190: 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
91a0: 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
91b0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79  ..** If the busy
91c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
91d0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a   NULL, then the.
91e0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c  ** callback will
91f0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
9200: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20   two arguments. 
9210: 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72   The.** first ar
9220: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61  gument to the ha
9230: 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
9240: 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
9250: 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
9260: 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
9270: 65 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74  ent to this rout
9280: 69 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ine.  The second
9290: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
92a0: 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74  the handler is t
92b0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
92c0: 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
92d0: 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
92e0: 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
92f0: 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
9300: 65 6e 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20 62  ent. If the.** b
9310: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
9320: 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
9330: 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
9340: 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
9350: 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
9360: 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
9370: 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
9380: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
9390: 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
93a0: 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  ** If the callba
93b0: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
93c0: 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
93d0: 72 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  r attempt is mad
93e0: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 0a 2a 2a  e to open the.**
93f0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
9400: 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
9410: 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
9420: 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
9430: 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
9440: 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
9450: 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20  ntee that.** it 
9460: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
9470: 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
9480: 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a  ck contention..*
9490: 2a 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65  * If SQLite dete
94a0: 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
94b0: 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
94c0: 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
94d0: 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c  lt in.** a deadl
94e0: 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 72 65 74  ock, it will ret
94f0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
9500: 5d 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 20 43 6f  ] instead..** Co
9510: 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
9520: 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
9530: 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
9540: 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
9550: 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
9560: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
9570: 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
9580: 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
9590: 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
95a0: 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
95b0: 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
95c0: 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
95d0: 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
95e0: 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
95f0: 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
9600: 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
9610: 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
9620: 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
9630: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
9640: 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
9650: 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
9660: 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
9670: 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
9680: 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
9690: 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
96a0: 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
96b0: 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
96c0: 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
96d0: 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
96e0: 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
96f0: 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
9700: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
9710: 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
9720: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
9730: 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
9740: 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
9750: 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
9760: 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
9770: 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
9780: 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oceed..**.** The
9790: 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
97a0: 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
97b0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
97c0: 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
97d0: 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
97e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
97f0: 4b 45 44 5d 20 77 68 65 6e 0a 2a 2a 20 53 51 4c  KED] when.** SQL
9800: 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
9810: 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
9820: 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
9830: 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
9840: 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
9850: 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
9860: 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
9870: 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
9880: 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
9890: 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
98a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
98b0: 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
98c0: 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
98d0: 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
98e0: 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
98f0: 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
9900: 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
9910: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
9920: 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
9930: 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
9940: 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61  s.  If it is una
9950: 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
9960: 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
9970: 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
9980: 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
9990: 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
99a0: 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
99b0: 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
99c0: 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
99d0: 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
99e0: 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
99f0: 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
9a00: 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
9a10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
9a20: 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72  CKED].  This err
9a30: 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
9a40: 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
9a50: 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
9a60: 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
9a70: 2e 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20  . See the.** <a 
9a80: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
9a90: 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74  .sqlite.org/cvst
9aa0: 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
9ab0: 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
9ac0: 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
9ad0: 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
9ae0: 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
9af0: 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
9b00: 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
9b10: 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
9b20: 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 53 71 6c  tant..**..** Sql
9b30: 69 74 65 20 69 73 20 72 65 2d 65 6e 74 72 61 6e  ite is re-entran
9b40: 74 2c 20 73 6f 20 74 68 65 20 62 75 73 79 20 68  t, so the busy h
9b50: 61 6e 64 6c 65 72 20 6d 61 79 20 73 74 61 72 74  andler may start
9b60: 20 61 20 6e 65 77 20 71 75 65 72 79 2e 20 0a 2a   a new query. .*
9b70: 2a 20 28 49 74 20 69 73 20 6e 6f 74 20 63 6c 65  * (It is not cle
9b80: 61 72 20 77 68 79 20 61 6e 79 6f 6e 65 20 77 6f  ar why anyone wo
9b90: 75 6c 64 20 65 76 65 72 79 20 77 61 6e 74 20 74  uld every want t
9ba0: 6f 20 64 6f 20 74 68 69 73 2c 20 62 75 74 20 69  o do this, but i
9bb0: 74 0a 2a 2a 20 69 73 20 61 6c 6c 6f 77 65 64 2c  t.** is allowed,
9bc0: 20 69 6e 20 74 68 65 6f 72 79 2e 29 20 20 42 75   in theory.)  Bu
9bd0: 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
9be0: 65 72 20 6d 61 79 20 6e 6f 74 20 63 6c 6f 73 65  er may not close
9bf0: 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
9c00: 2e 20 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 64  .  Closing the d
9c10: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 61 20 62  atabase from a b
9c20: 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c  usy handler will
9c30: 20 64 65 6c 65 74 65 20 0a 2a 2a 20 64 61 74 61   delete .** data
9c40: 20 73 74 72 75 63 74 75 72 65 73 20 6f 75 74 20   structures out 
9c50: 66 72 6f 6d 20 75 6e 64 65 72 20 74 68 65 20 65  from under the e
9c60: 78 65 63 75 74 69 6e 67 20 71 75 65 72 79 20 61  xecuting query a
9c70: 6e 64 20 77 69 6c 6c 20 0a 2a 2a 20 70 72 6f 62  nd will .** prob
9c80: 61 62 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 61  ably result in a
9c90: 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
9ca0: 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 72 75 6e  ult or other run
9cb0: 74 69 6d 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  time error..**.*
9cc0: 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  * There can only
9cd0: 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
9ce0: 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
9cf0: 64 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62  d for each datab
9d00: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9d10: 6e 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  n.  Setting a ne
9d20: 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
9d30: 6c 65 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f  lears any previo
9d40: 75 73 20 6f 6e 65 2e 0a 2a 2a 20 4e 6f 74 65 20  us one..** Note 
9d50: 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
9d60: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
9d70: 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20  ut()] will also 
9d80: 73 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20  set or clear.** 
9d90: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
9da0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 6f 70 65  ..**.** When ope
9db0: 72 61 74 69 6e 67 20 69 6e 20 5b 73 71 6c 69 74  rating in [sqlit
9dc0: 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
9dd0: 5f 63 61 63 68 65 20 7c 20 73 68 61 72 65 64 20  _cache | shared 
9de0: 63 61 63 68 65 20 6d 6f 64 65 5d 2c 0a 2a 2a 20  cache mode],.** 
9df0: 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 62 75  only a single bu
9e00: 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6e 20 62  sy handler can b
9e10: 65 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  e defined for ea
9e20: 63 68 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ch database file
9e30: 2e 0a 2a 2a 20 53 6f 20 69 66 20 74 77 6f 20 64  ..** So if two d
9e40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9e50: 6f 6e 73 20 73 68 61 72 65 20 61 20 73 69 6e 67  ons share a sing
9e60: 6c 65 20 63 61 63 68 65 2c 20 74 68 65 6e 20 63  le cache, then c
9e70: 68 61 6e 67 69 6e 67 0a 2a 2a 20 74 68 65 20 62  hanging.** the b
9e80: 75 73 79 20 68 61 6e 64 6c 65 72 20 6f 6e 20 6f  usy handler on o
9e90: 6e 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69  ne connection wi
9ea0: 6c 6c 20 61 6c 73 6f 20 63 68 61 6e 67 65 20 74  ll also change t
9eb0: 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
9ec0: 65 72 20 69 6e 20 74 68 65 20 6f 74 68 65 72 20  er in the other 
9ed0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
9ee0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
9ef0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 69 6e 20 74   invoked.** in t
9f00: 68 65 20 74 68 72 65 61 64 20 74 68 61 74 20 77  he thread that w
9f10: 61 73 20 72 75 6e 6e 69 6e 67 20 77 68 65 6e 20  as running when 
9f20: 74 68 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  the SQLITE_BUSY 
9f30: 77 61 73 20 68 69 74 2e 0a 2a 2f 0a 69 6e 74 20  was hit..*/.int 
9f40: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
9f50: 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
9f60: 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
9f70: 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
9f80: 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
9f90: 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
9fa0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
9fb0: 20 73 65 74 73 20 61 20 62 75 73 79 20 68 61 6e   sets a busy han
9fc0: 64 6c 65 72 20 74 68 61 74 20 73 6c 65 65 70 73  dler that sleeps
9fd0: 20 66 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65   for a while whe
9fe0: 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20  n a.** table is 
9ff0: 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e  locked.  The han
a000: 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 70 20  dler will sleep 
a010: 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
a020: 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73  ntil .** at leas
a030: 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
a040: 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20  nds of sleeping 
a050: 68 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20  have been done. 
a060: 20 41 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d   After.** "ms" m
a070: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
a080: 6c 65 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e  leeping, the han
a090: 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
a0a0: 68 69 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b  hich.** causes [
a0b0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
a0c0: 74 6f 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  to return [SQLIT
a0d0: 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
a0e0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
a0f0: 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  ]..**.** Calling
a100: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
a110: 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
a120: 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
a130: 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
a140: 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
a150: 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
a160: 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
a170: 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
a180: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
a190: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
a1a0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
a1b0: 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
a1c0: 79 20 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65  y handler was de
a1d0: 66 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e  fined  .** (usin
a1e0: 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
a1f0: 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
a200: 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
a210: 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
a220: 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
a230: 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
a240: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
a250: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
a260: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
a270: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a280: 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
a290: 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
a2a0: 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
a2b0: 20 54 68 69 73 20 6e 65 78 74 20 72 6f 75 74 69   This next routi
a2c0: 6e 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ne is a convenie
a2d0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
a2e0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  nd [sqlite3_exec
a2f0: 28 29 5d 2e 0a 2a 2a 20 49 6e 73 74 65 61 64 20  ()]..** Instead 
a300: 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 61 20 75 73  of invoking a us
a310: 65 72 2d 73 75 70 70 6c 69 65 64 20 63 61 6c 6c  er-supplied call
a320: 62 61 63 6b 20 66 6f 72 20 65 61 63 68 20 72 6f  back for each ro
a330: 77 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 73 75  w of the.** resu
a340: 6c 74 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  lt, this routine
a350: 20 72 65 6d 65 6d 62 65 72 73 20 65 61 63 68 20   remembers each 
a360: 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
a370: 74 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f  t in memory.** o
a380: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a390: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
a3a0: 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 6c   then returns al
a3b0: 6c 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  l of the result 
a3c0: 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 71 75 65  after the.** que
a3d0: 72 79 20 68 61 73 20 66 69 6e 69 73 68 65 64 2e  ry has finished.
a3e0: 20 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78   .**.** As an ex
a3f0: 61 6d 70 6c 65 2c 20 73 75 70 70 6f 73 65 20 74  ample, suppose t
a400: 68 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  he query result 
a410: 77 68 65 72 65 20 74 68 69 73 20 74 61 62 6c 65  where this table
a420: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
a430: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
a440: 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
a450: 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
a460: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
a470: 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
a480: 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
a490: 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
a4a0: 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
a4b0: 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
a4c0: 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
a4d0: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
a4e0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
a4f0: 20 61 72 67 75 6d 65 6e 74 20 77 65 72 65 20 26   argument were &
a500: 61 7a 52 65 73 75 6c 74 20 74 68 65 6e 20 61 66  azResult then af
a510: 74 65 72 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ter the function
a520: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 7a 52 65   returns.** azRe
a530: 73 75 6c 74 20 77 69 6c 6c 20 63 6f 6e 74 61 69  sult will contai
a540: 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
a550: 64 61 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  data:.**.** <blo
a560: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
a570: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
a580: 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
a590: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
a5a0: 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
a5b0: 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
a5c0: 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
a5d0: 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
a5e0: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
a5f0: 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
a600: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
a610: 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
a620: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
a630: 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
a640: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
a650: 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
a660: 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
a670: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
a680: 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
a690: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
a6a0: 2a 0a 2a 2a 20 4e 6f 74 69 63 65 20 74 68 61 74  *.** Notice that
a6b0: 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 78 74   there is an ext
a6c0: 72 61 20 72 6f 77 20 6f 66 20 64 61 74 61 20 63  ra row of data c
a6d0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 63 6f  ontaining the co
a6e0: 6c 75 6d 6e 0a 2a 2a 20 68 65 61 64 65 72 73 2e  lumn.** headers.
a6f0: 20 20 42 75 74 20 74 68 65 20 2a 6e 72 6f 77 20    But the *nrow 
a700: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20  return value is 
a710: 73 74 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f 6c 75  still 3.  *ncolu
a720: 6d 6e 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20  mn is.** set to 
a730: 32 2e 20 20 49 6e 20 67 65 6e 65 72 61 6c 2c 20  2.  In general, 
a740: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  the number of va
a750: 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20 69 6e  lues inserted in
a760: 74 6f 20 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 77  to azResult.** w
a770: 69 6c 6c 20 62 65 20 28 28 2a 6e 72 6f 77 29 20  ill be ((*nrow) 
a780: 2b 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e 29 2e  + 1)*(*ncolumn).
a790: 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
a7a0: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
a7b0: 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  n has finished u
a7c0: 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c  sing the result,
a7d0: 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70   it should .** p
a7e0: 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 64  ass the result d
a7f0: 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ata pointer to s
a800: 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
a810: 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  e() in order to 
a820: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
a830: 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
a840: 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61  malloc-ed.  Beca
a850: 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
a860: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
a870: 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
a880: 73 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  s, the calling f
a890: 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
a8a0: 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 0a 2a 2a   try to call .**
a8b0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
a8c0: 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
a8d0: 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  y [sqlite3_free_
a8e0: 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
a8f0: 20 74 6f 20 72 65 6c 65 61 73 65 20 0a 2a 2a 20   to release .** 
a900: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
a910: 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
a920: 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  **.** The return
a930: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72   value of this r
a940: 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 73 61  outine is the sa
a950: 6d 65 20 61 73 20 66 72 6f 6d 20 5b 73 71 6c 69  me as from [sqli
a960: 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2f 0a  te3_exec()]..*/.
a970: 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
a980: 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
a990: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
a9a0: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
a9b0: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
a9c0: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
a9d0: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 78 65  /* SQL to be exe
a9e0: 63 75 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  cuted */.  char 
a9f0: 2a 2a 2a 72 65 73 75 6c 74 70 2c 20 20 20 20 20  ***resultp,     
aa00: 20 20 2f 2a 20 52 65 73 75 6c 74 20 77 72 69 74    /* Result writ
aa10: 74 65 6e 20 74 6f 20 61 20 63 68 61 72 20 2a 5b  ten to a char *[
aa20: 5d 20 20 74 68 61 74 20 74 68 69 73 20 70 6f 69  ]  that this poi
aa30: 6e 74 73 20 74 6f 20 2a 2f 0a 20 20 69 6e 74 20  nts to */.  int 
aa40: 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20  *nrow,          
aa50: 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
aa60: 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
aa70: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
aa80: 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20  t *ncolumn,     
aa90: 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
aaa0: 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
aab0: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
aac0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
aad0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
aae0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
aaf0: 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
ab00: 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
ab10: 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
ab20: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ab30: 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
ab40: 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
ab50: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
ab60: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
ab70: 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68  workalikes of th
ab80: 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
ab90: 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
aba0: 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
abb0: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
abc0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
abd0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
abe0: 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
abf0: 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
ac00: 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
ac10: 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
ac20: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
ac30: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
ac40: 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
ac50: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
ac60: 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
ac70: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
ac80: 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
ac90: 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68  3_free()].  Both
aca0: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
acb0: 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
acc0: 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
acd0: 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
ace0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
acf0: 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
ad00: 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
ad10: 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
ad20: 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73  .** In sqlite3_s
ad30: 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
ad40: 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
ad50: 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
ad60: 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
ad70: 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
ad80: 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
ad90: 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
ada0: 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
adb0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
adc0: 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
add0: 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
ade0: 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
adf0: 6d 65 74 65 72 2e 20 20 4e 6f 74 65 20 74 68 61  meter.  Note tha
ae00: 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
ae10: 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
ae20: 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
ae30: 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
ae40: 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73  intf().  This is
ae50: 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
ae60: 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
ae70: 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
ae80: 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
ae90: 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
aea0: 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f  mpatibility.  No
aeb0: 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
aec0: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
aed0: 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
aee0: 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
aef0: 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
af00: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
af10: 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
af20: 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
af30: 74 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20  the buffer.  We 
af40: 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
af50: 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
af60: 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
af70: 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
af80: 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
af90: 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
afa0: 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
afb0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
afc0: 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
afd0: 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
afe0: 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
aff0: 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
b000: 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   As long as the 
b010: 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
b020: 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
b030: 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
b040: 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
b050: 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
b060: 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
b070: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54  o-terminated.  T
b080: 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
b090: 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
b0a0: 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
b0b0: 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
b0c0: 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
b0d0: 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
b0e0: 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
b0f0: 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
b100: 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
b110: 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
b120: 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
b130: 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  acters..**.** Th
b140: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
b150: 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
b160: 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
b170: 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
b180: 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
b190: 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
b1a0: 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
b1b0: 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
b1c0: 75 73 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72  usual printf for
b1d0: 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
b1e0: 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
b1f0: 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
b200: 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
b210: 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
b220: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20  s..**.** The %q 
b230: 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
b240: 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
b250: 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
b260: 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
b270: 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
b280: 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
b290: 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
b2a0: 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
b2b0: 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
b2c0: 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
b2d0: 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
b2e0: 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42  ring literal.  B
b2f0: 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
b300: 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
b310: 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
b320: 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
b330: 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
b340: 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
b350: 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
b360: 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
b370: 73 6f 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76  so some string v
b380: 61 72 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73  ariable contains
b390: 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
b3a0: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
b3b0: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
b3c0: 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
b3d0: 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
b3e0: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
b3f0: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
b400: 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
b410: 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
b420: 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
b430: 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
b440: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
b450: 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
b460: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
b470: 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
b480: 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
b490: 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
b4a0: 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
b4b0: 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
b4c0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
b4d0: 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
b4e0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
b4f0: 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
b500: 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
b510: 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
b520: 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
b530: 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
b540: 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
b550: 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
b560: 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
b570: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
b580: 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
b590: 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
b5a0: 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
b5b0: 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
b5c0: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
b5d0: 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
b5e0: 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
b5f0: 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
b600: 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
b610: 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
b620: 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
b630: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
b640: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
b650: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
b660: 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
b670: 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
b680: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
b690: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
b6a0: 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
b6b0: 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
b6c0: 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
b6d0: 72 61 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20  ral rule you.** 
b6e0: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73  should always us
b6f0: 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
b700: 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
b710: 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
b720: 72 69 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c  ring .** literal
b730: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f  ..**.** The %Q o
b740: 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
b750: 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
b760: 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
b770: 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
b780: 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
b790: 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
b7a0: 20 20 4f 72 20 69 66 20 74 68 65 20 70 61 72 61    Or if the para
b7b0: 6d 65 74 65 72 20 69 6e 20 74 68 65 20 61 72 67  meter in the arg
b7c0: 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73  ument.** list is
b7d0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
b7e0: 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
b7f0: 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
b800: 28 77 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a  (without single.
b810: 2a 2a 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c  ** quotes) in pl
b820: 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70  ace of the %Q op
b830: 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65  tion.  So, for e
b840: 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
b850: 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
b860: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
b870: 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
b880: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
b890: 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
b8a0: 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
b8b0: 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
b8c0: 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
b8d0: 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
b8e0: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
b8f0: 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
b900: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
b910: 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
b920: 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
b930: 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
b940: 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
b950: 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
b960: 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
b970: 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
b980: 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
b990: 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74   The "%z" format
b9a0: 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
b9b0: 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22  s exactly like "
b9c0: 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  %s" with the.** 
b9d0: 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
b9e0: 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
b9f0: 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
ba00: 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
ba10: 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
ba20: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
ba30: 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
ba40: 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2f 0a 63  put string..*/.c
ba50: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
ba60: 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
ba70: 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
ba80: 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
ba90: 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
baa0: 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
bab0: 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
bac0: 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
bad0: 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, ...);../*.** 
bae0: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
baf0: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
bb00: 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
bb10: 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
bb20: 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
bb30: 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
bb40: 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
bb50: 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
bb60: 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 28 53  cation needs. (S
bb70: 65 65 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e  ee the exception
bb80: 20 62 65 6c 6f 77 2e 29 0a 2a 2a 20 54 68 65 20   below.).** The 
bb90: 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e  default implemen
bba0: 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
bbb0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bbc0: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65  on subsystem use
bbd0: 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20  s the malloc(), 
bbe0: 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64  realloc().** and
bbf0: 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64   free() provided
bc00: 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64   by the standard
bc10: 20 43 20 6c 69 62 72 61 72 79 2e 20 20 48 6f 77   C library.  How
bc20: 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c  ever, if .** SQL
bc30: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
bc40: 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69  with the followi
bc50: 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  ng C preprocesso
bc60: 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62  r macro.**.** <b
bc70: 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54  lockquote> SQLIT
bc80: 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
bc90: 4c 4f 43 41 54 49 4f 4e 20 3c 2f 62 6c 6f 63 6b  LOCATION </block
bca0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 74 68 65  quote>.**.** the
bcb0: 6e 20 6e 6f 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n no implementat
bcc0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
bcd0: 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
bce0: 65 73 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 2e  es by.** SQLite.
bcf0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
bd00: 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  n that links aga
bd10: 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a  inst SQLite is.*
bd20: 2a 20 65 78 70 65 63 74 65 64 20 74 6f 20 70 72  * expected to pr
bd30: 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20 69 6d  ovide its own im
bd40: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 49  plementation.  I
bd50: 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
bd60: 6e 0a 2a 2a 20 64 6f 65 73 20 70 72 6f 76 69 64  n.** does provid
bd70: 65 20 69 74 73 20 6f 77 6e 20 69 6d 70 6c 65 6d  e its own implem
bd80: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  entation for the
bd90: 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 74 68 65  se routines, the
bda0: 6e 0a 2a 2a 20 69 74 20 6d 75 73 74 20 61 6c 73  n.** it must als
bdb0: 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70  o provide an imp
bdc0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
bdd0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
bde0: 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 2c 20 5b 73  ory_alarm()], [s
bdf0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
be00: 65 64 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  ed()], and.** [s
be10: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
be20: 67 68 77 61 74 65 72 28 29 5d 2e 20 20 54 68 65  ghwater()].  The
be30: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
be40: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
be50: 66 6f 72 20 74 68 65 73 65 20 6c 61 73 74 20 74  for these last t
be60: 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 6e 65  hree routines ne
be70: 65 64 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  ed not actually 
be80: 77 6f 72 6b 2c 20 62 75 74 0a 2a 2a 20 73 74 75  work, but.** stu
be90: 62 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 20 6c  b functions at l
bea0: 65 61 73 74 20 61 72 65 20 6e 65 65 64 65 64 20  east are needed 
beb0: 74 6f 20 73 74 61 74 69 73 66 79 20 74 68 65 20  to statisfy the 
bec0: 6c 69 6e 6b 65 72 2e 0a 2a 2a 20 53 51 4c 69 74  linker..** SQLit
bed0: 65 20 6e 65 76 65 72 20 63 61 6c 6c 73 20 5b 73  e never calls [s
bee0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
bef0: 67 68 77 61 74 65 72 28 29 5d 20 69 74 73 65 6c  ghwater()] itsel
bf00: 66 2c 20 62 75 74 0a 2a 2a 20 74 68 65 20 73 79  f, but.** the sy
bf10: 6d 62 6f 6c 20 69 73 20 69 6e 63 6c 75 64 65 64  mbol is included
bf20: 20 69 6e 20 61 20 74 61 62 6c 65 20 61 73 20 70   in a table as p
bf30: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  art of the.** [s
bf40: 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
bf50: 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
bf60: 63 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ce.  The.** [sql
bf70: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
bf80: 6d 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  m()] and [sqlite
bf90: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
bfa0: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
bfb0: 72 65 20 63 61 6c 6c 65 64 20 62 79 20 5b 73 71  re called by [sq
bfc0: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
bfd0: 6c 69 6d 69 74 28 29 5d 20 61 6e 64 20 77 6f 72  limit()] and wor
bfe0: 6b 69 6e 67 20 69 6d 70 6c 65 6d 65 6e 74 61 74  king implementat
bff0: 69 6f 6e 73 0a 2a 2a 20 6f 66 20 62 6f 74 68 20  ions.** of both 
c000: 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
c010: 20 70 72 6f 76 69 64 65 64 20 69 66 20 5b 73 71   provided if [sq
c020: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
c030: 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 69 73 20 74  limit()].** is t
c040: 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63  o operate correc
c050: 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 45 78  tly..**.** <b>Ex
c060: 63 65 70 74 69 6f 6e 3a 3c 2f 62 3e 20 54 68 65  ception:</b> The
c070: 20 77 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   windows OS inte
c080: 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
c090: 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
c0a0: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
c0b0: 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
c0c0: 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
c0d0: 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
c0e0: 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
c0f0: 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
c100: 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
c110: 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
c120: 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
c130: 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
c140: 77 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  windows.** insta
c150: 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
c160: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
c170: 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
c180: 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
c190: 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
c1a0: 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
c1b0: 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
c1c0: 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
c1d0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
c1e0: 45 4d 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  EM]..*/.void *sq
c1f0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
c200: 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
c210: 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
c220: 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
c230: 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
c240: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c250: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
c260: 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
c270: 2a 2a 20 49 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** In addition t
c280: 6f 20 74 68 65 20 62 61 73 69 63 20 74 68 72 65  o the basic thre
c290: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  e allocation rou
c2a0: 74 69 6e 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  tines .** [sqlit
c2b0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
c2c0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
c2d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
c2e0: 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 74 68 65 20  lloc()],.** the 
c2f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c300: 6e 20 73 75 62 73 79 73 74 65 6d 20 69 6e 63 6c  n subsystem incl
c310: 75 64 65 64 20 77 69 74 68 20 74 68 65 20 53 51  uded with the SQ
c320: 4c 69 74 65 0a 2a 2a 20 73 6f 75 72 63 65 73 20  Lite.** sources 
c330: 70 72 6f 76 69 64 65 73 20 74 68 65 20 69 6e 74  provides the int
c340: 65 72 66 61 63 65 73 20 73 68 6f 77 6e 20 62 65  erfaces shown be
c350: 6c 6f 77 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  low..**.** The f
c360: 69 72 73 74 20 6f 66 20 74 68 65 73 65 20 74 77  irst of these tw
c370: 6f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  o routines retur
c380: 6e 73 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ns the amount of
c390: 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 63 75 72 72   memory .** curr
c3a0: 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
c3b0: 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
c3c0: 6e 6f 74 20 66 72 65 65 64 29 2e 20 20 54 68 65  not freed).  The
c3d0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 74 75 72   second.** retur
c3e0: 6e 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 69  ns the largest i
c3f0: 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 61 6d 6f  nstantaneous amo
c400: 75 6e 74 20 6f 66 20 6f 75 74 73 74 61 6e 64 69  unt of outstandi
c410: 6e 67 0a 2a 2a 20 6d 65 6d 6f 72 79 2e 20 20 54  ng.** memory.  T
c420: 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72  he highwater mar
c430: 6b 20 69 73 20 72 65 73 65 74 20 69 66 20 74 68  k is reset if th
c440: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  e argument is.**
c450: 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   true..**.** The
c460: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
c470: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
c480: 73 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  s in the SQLite 
c490: 63 6f 72 65 0a 2a 2a 20 69 73 20 6f 6d 69 74 74  core.** is omitt
c4a0: 65 64 20 69 66 20 74 68 65 20 61 70 70 6c 69 63  ed if the applic
c4b0: 61 74 69 6f 6e 20 69 73 20 63 6f 6d 70 69 6c 65  ation is compile
c4c0: 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
c4d0: 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
c4e0: 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 6d 61 63 72  _ALLOCATION macr
c4f0: 6f 20 64 65 66 69 6e 65 64 2e 20 20 49 6e 20 74  o defined.  In t
c500: 68 61 74 20 63 61 73 65 2c 0a 2a 2a 20 74 68 65  hat case,.** the
c510: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
c520: 74 20 6c 69 6e 6b 73 20 53 51 4c 69 74 65 20 6d  t links SQLite m
c530: 75 73 74 20 70 72 6f 76 69 64 65 20 69 74 73 20  ust provide its 
c540: 6f 77 6e 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  own.** alternati
c550: 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
c560: 6e 2e 20 20 53 65 65 20 74 68 65 20 64 6f 63 75  n.  See the docu
c570: 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 0a 2a 2a 20  mentation on.** 
c580: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
c590: 29 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  )] for additiona
c5a0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
c5b0: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
c5c0: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
c5d0: 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
c5e0: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
c5f0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
c600: 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
c610: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
c620: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
c630: 74 69 6f 6e 20 41 6c 61 72 6d 73 0a 2a 2a 0a 2a  tion Alarms.**.*
c640: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
c650: 65 6d 6f 72 79 5f 61 6c 61 72 6d 5d 20 72 6f 75  emory_alarm] rou
c660: 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20  tine is used to 
c670: 72 65 67 69 73 74 65 72 0a 2a 2a 20 61 20 63 61  register.** a ca
c680: 6c 6c 62 61 63 6b 20 6f 6e 20 6d 65 6d 6f 72 79  llback on memory
c690: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 76 65 6e   allocation even
c6a0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ts..**.** This r
c6b0: 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
c6c0: 20 6f 72 20 63 6c 65 61 72 73 20 61 20 63 61 6c   or clears a cal
c6d0: 6c 62 61 63 6b 73 20 74 68 61 74 20 66 69 72 65  lbacks that fire
c6e0: 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 61 6d  s when.** the am
c6f0: 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ount of memory a
c700: 6c 6c 6f 63 61 74 65 64 20 65 78 63 65 65 64 73  llocated exceeds
c710: 20 69 54 68 72 65 73 68 6f 6c 64 2e 20 20 4f 6e   iThreshold.  On
c720: 6c 79 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63  ly.** a single c
c730: 61 6c 6c 62 61 63 6b 20 63 61 6e 20 62 65 20 72  allback can be r
c740: 65 67 69 73 74 65 72 65 64 20 61 74 20 61 20 74  egistered at a t
c750: 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 0a  ime.  Each call.
c760: 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ** to [sqlite3_m
c770: 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 20 6f  emory_alarm()] o
c780: 76 65 72 77 72 69 74 65 73 20 74 68 65 20 70 72  verwrites the pr
c790: 65 76 69 6f 75 73 20 63 61 6c 6c 62 61 63 6b 2e  evious callback.
c7a0: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
c7b0: 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
c7c0: 73 65 74 74 69 6e 67 20 78 43 61 6c 6c 62 61 63  setting xCallbac
c7d0: 6b 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  k to a NULL.** p
c7e0: 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54  ointer..** .** T
c7f0: 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  he parameters to
c800: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
c810: 65 20 74 68 65 20 70 41 72 67 20 76 61 6c 75 65  e the pArg value
c820: 2c 20 74 68 65 20 0a 2a 2a 20 61 6d 6f 75 6e 74  , the .** amount
c830: 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
c840: 6e 74 6c 79 20 69 6e 20 75 73 65 2c 20 61 6e 64  ntly in use, and
c850: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
c860: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  .** allocation t
c870: 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65  hat provoked the
c880: 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 20   callback.  The 
c890: 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 0a 2a 2a  callback will.**
c8a0: 20 70 72 65 73 75 6d 61 62 6c 79 20 69 6e 76 6f   presumably invo
c8b0: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
c8c0: 28 29 5d 20 74 6f 20 66 72 65 65 20 75 70 20 6d  ()] to free up m
c8d0: 65 6d 6f 72 79 20 73 70 61 63 65 2e 0a 2a 2a 20  emory space..** 
c8e0: 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  The callback may
c8f0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
c900: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
c910: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
c920: 5d 0a 2a 2a 20 62 75 74 20 69 66 20 69 74 20 64  ].** but if it d
c930: 6f 65 73 2c 20 6e 6f 20 61 64 64 69 74 69 6f 6e  oes, no addition
c940: 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 77 69 6c  al callbacks wil
c950: 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 0a  l be invoked by.
c960: 2a 2a 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ** the recursive
c970: 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   calls..**.** Th
c980: 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  e [sqlite3_soft_
c990: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  heap_limit()] in
c9a0: 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 62 79  terface works by
c9b0: 20 72 65 67 69 73 74 65 72 69 6e 67 0a 2a 2a 20   registering.** 
c9c0: 61 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20 61  a memory alarm a
c9d0: 74 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  t the soft heap 
c9e0: 6c 69 6d 69 74 20 61 6e 64 20 69 6e 76 6f 6b 69  limit and invoki
c9f0: 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
ca00: 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
ca10: 5d 20 69 6e 20 74 68 65 20 61 6c 61 72 6d 20 63  ] in the alarm c
ca20: 61 6c 6c 62 61 63 6b 2e 20 20 41 70 70 6c 69 63  allback.  Applic
ca30: 61 74 69 6f 6e 0a 2a 2a 20 70 72 6f 67 72 61 6d  ation.** program
ca40: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 61 74 74  s should not att
ca50: 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
ca60: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
ca70: 61 6c 61 72 6d 28 29 5d 0a 2a 2a 20 69 6e 74 65  alarm()].** inte
ca80: 72 66 61 63 65 20 62 65 63 61 75 73 65 20 64 6f  rface because do
ca90: 69 6e 67 20 73 6f 20 77 69 6c 6c 20 69 6e 74 65  ing so will inte
caa0: 72 66 65 72 65 20 77 69 74 68 20 74 68 65 0a 2a  rfere with the.*
cab0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  * [sqlite3_soft_
cac0: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 20 6d 6f  heap_limit()] mo
cad0: 64 75 6c 65 2e 20 20 54 68 69 73 20 69 6e 74 65  dule.  This inte
cae0: 72 66 61 63 65 20 69 73 20 65 78 70 6f 73 65 64  rface is exposed
caf0: 0a 2a 2a 20 6f 6e 6c 79 20 73 6f 20 74 68 61 74  .** only so that
cb00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 63 61   applications ca
cb10: 6e 20 70 72 6f 76 69 64 65 20 74 68 65 69 72 20  n provide their 
cb20: 6f 77 6e 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  own.** alternati
cb30: 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
cb40: 6e 20 77 68 65 6e 20 74 68 65 20 53 51 4c 69 74  n when the SQLit
cb50: 65 20 63 6f 72 65 20 69 73 0a 2a 2a 20 63 6f 6d  e core is.** com
cb60: 70 69 6c 65 64 20 77 69 74 68 20 53 51 4c 49 54  piled with SQLIT
cb70: 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
cb80: 4c 4f 43 41 54 49 4f 4e 2e 0a 2a 2f 0a 69 6e 74  LOCATION..*/.int
cb90: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
cba0: 61 6c 61 72 6d 28 0a 20 20 76 6f 69 64 28 2a 78  alarm(.  void(*x
cbb0: 43 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 20 2a  Callback)(void *
cbc0: 70 41 72 67 2c 20 73 71 6c 69 74 65 33 5f 69 6e  pArg, sqlite3_in
cbd0: 74 36 34 20 75 73 65 64 2c 20 69 6e 74 20 4e 29  t64 used, int N)
cbe0: 2c 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a  ,.  void *pArg,.
cbf0: 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20    sqlite3_int64 
cc00: 69 54 68 72 65 73 68 6f 6c 64 0a 29 3b 0a 0a 0a  iThreshold.);...
cc10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
cc20: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
cc30: 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
cc40: 61 63 6b 73 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73  acks.***.** This
cc50: 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
cc60: 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
cc70: 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 74 68  callback with th
cc80: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
cc90: 2e 20 20 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .  .** The autho
cca0: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
ccb0: 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
ccc0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
ccd0: 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
cce0: 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
ccf0: 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
cd00: 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
cd10: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
cd20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
cd30: 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
cd40: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
cd50: 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69  _v2()].  At vari
cd60: 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
cd70: 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
cd80: 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
cd90: 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
cda0: 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
cdb0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
cdc0: 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
cdd0: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
cde0: 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
cdf0: 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
ce00: 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
ce10: 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  .  The authorize
ce20: 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
ce30: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 53 51 4c 49  d.** return SQLI
ce40: 54 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f 77 20 74  TE_OK to allow t
ce50: 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
ce60: 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
ce70: 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
ce80: 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
ce90: 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
cea0: 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
ceb0: 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
cec0: 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
ced0: 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
cee0: 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
cef0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
cf00: 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
cf10: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a 2a  th an error.  .*
cf20: 2a 0a 2a 2a 20 44 65 70 65 6e 64 69 6e 67 20 6f  *.** Depending o
cf30: 6e 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 74 68  n the action, th
cf40: 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
cf50: 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45  ] and [SQLITE_DE
cf60: 4e 59 5d 20 72 65 74 75 72 6e 0a 2a 2a 20 63 6f  NY] return.** co
cf70: 64 65 73 20 6d 69 67 68 74 20 6d 65 61 6e 20 73  des might mean s
cf80: 6f 6d 65 74 68 69 6e 67 20 64 69 66 66 65 72 65  omething differe
cf90: 6e 74 20 6f 72 20 74 68 65 79 20 6d 69 67 68 74  nt or they might
cfa0: 20 6d 65 61 6e 20 74 68 65 20 73 61 6d 65 0a 2a   mean the same.*
cfb0: 2a 20 74 68 69 6e 67 2e 20 20 49 66 20 74 68 65  * thing.  If the
cfc0: 20 61 63 74 69 6f 6e 20 69 73 2c 20 66 6f 72 20   action is, for 
cfd0: 65 78 61 6d 70 6c 65 2c 20 74 6f 20 70 65 72 66  example, to perf
cfe0: 6f 72 6d 20 61 20 64 65 6c 65 74 65 20 6f 70 65  orm a delete ope
cff0: 72 74 69 6f 6e 2c 0a 2a 2a 20 74 68 65 6e 20 5b  rtion,.** then [
d000: 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61  SQLITE_IGNORE] a
d010: 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  nd [SQLITE_DENY]
d020: 20 62 6f 74 68 20 63 61 75 73 65 20 74 68 65 20   both cause the 
d030: 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
d040: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 61 69 6c  ation.** to fail
d050: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
d060: 20 42 75 74 20 69 66 20 74 68 65 20 61 63 74 69   But if the acti
d070: 6f 6e 20 69 73 20 74 6f 20 72 65 61 64 20 61 20  on is to read a 
d080: 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 0a  specific column.
d090: 2a 2a 20 66 72 6f 6d 20 61 20 73 70 65 63 69 66  ** from a specif
d0a0: 69 63 20 74 61 62 6c 65 2c 20 74 68 65 6e 20 5b  ic table, then [
d0b0: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 77 69 6c  SQLITE_DENY] wil
d0c0: 6c 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  l cause the enti
d0d0: 72 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  re.** statement 
d0e0: 74 6f 20 66 61 69 6c 20 62 75 74 20 5b 53 51 4c  to fail but [SQL
d0f0: 49 54 45 5f 49 47 4e 4f 52 45 5d 20 77 69 6c 6c  ITE_IGNORE] will
d100: 20 63 61 75 73 65 20 61 20 4e 55 4c 4c 20 76 61   cause a NULL va
d110: 6c 75 65 20 74 6f 20 62 65 0a 2a 2a 20 72 65 61  lue to be.** rea
d120: 64 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  d instead of the
d130: 20 61 63 74 75 61 6c 20 63 6f 6c 75 6d 6e 20 76   actual column v
d140: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
d150: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
d160: 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
d170: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
d180: 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74  copy of.** the t
d190: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
d1a0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
d1b0: 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
d1c0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65  nterface..** The
d1d0: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
d1e0: 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
d1f0: 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
d200: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  .** [SQLITE_COPY
d210: 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
d220: 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
d230: 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
d240: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75  tion.** to be au
d250: 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 61  thorized.  The a
d260: 76 61 69 6c 61 62 6c 65 20 61 63 74 69 6f 6e 20  vailable action 
d270: 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 5b 53 51  codes are.** [SQ
d280: 4c 49 54 45 5f 43 4f 50 59 20 7c 20 64 6f 63 75  LITE_COPY | docu
d290: 6d 65 6e 74 65 64 20 73 65 70 61 72 61 74 65 6c  mented separatel
d2a0: 79 5d 2e 20 20 54 68 65 20 74 68 69 72 64 20 74  y].  The third t
d2b0: 68 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a 20  hrough sixth.** 
d2c0: 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
d2d0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 73  e callback are s
d2e0: 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
d2f0: 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
d300: 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
d310: 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
d320: 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
d330: 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
d340: 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 70 72   is used when pr
d350: 65 70 61 72 69 6e 67 20 53 51 4c 20 73 74 61 74  eparing SQL stat
d360: 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
d370: 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72  ntrusted.** sour
d380: 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
d390: 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
d3a0: 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79  ments do not try
d3b0: 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a   to access data.
d3c0: 2a 2a 20 74 68 61 74 20 74 68 65 79 20 61 72 65  ** that they are
d3d0: 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
d3e0: 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
d3f0: 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a  y do not try to.
d400: 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  ** execute malic
d410: 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
d420: 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
d430: 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
d440: 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
d450: 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
d460: 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
d470: 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
d480: 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
d490: 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
d4a0: 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
d4b0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
d4c0: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
d4d0: 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
d4e0: 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
d4f0: 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
d500: 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
d510: 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
d520: 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
d530: 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
d540: 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
d550: 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
d560: 69 6e 67 20 70 72 65 70 61 72 65 64 20 74 68 61  ing prepared tha
d570: 74 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  t disallows ever
d580: 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70 74  ything.** except
d590: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
d5a0: 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79  ts.  .**.** Only
d5b0: 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
d5c0: 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
d5d0: 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
d5e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
d5f0: 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
d600: 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
d610: 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
d620: 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
d630: 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
d640: 20 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69    A NULL authori
d650: 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  zer means that n
d660: 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  o authorization.
d670: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ** callback is i
d680: 6e 76 6f 6b 65 64 2e 20 20 54 68 65 20 64 65 66  nvoked.  The def
d690: 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20  ault authorizer 
d6a0: 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4e  is NULL..**.** N
d6b0: 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
d6c0: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
d6d0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
d6e0: 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c   during .** [sql
d6f0: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
d700: 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
d710: 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
d720: 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
d730: 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
d740: 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
d750: 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
d760: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
d770: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
d780: 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
d790: 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
d7a0: 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
d7b0: 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
d7c0: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
d7d0: 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
d7e0: 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
d7f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d800: 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
d810: 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
d820: 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
d830: 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
d840: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
d850: 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
d860: 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
d870: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
d880: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
d890: 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
d8a0: 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
d8b0: 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
d8c0: 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
d8d0: 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
d8e0: 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
d8f0: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
d900: 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
d910: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
d920: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
d930: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
d940: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d950: 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
d960: 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
d970: 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
d980: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
d990: 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
d9a0: 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
d9b0: 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
d9c0: 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
d9d0: 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
d9e0: 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
d9f0: 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
da00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
da10: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
da20: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
da30: 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
da40: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
da50: 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
da60: 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 63   to authorizer c
da70: 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
da80: 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
da90: 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
daa0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
dab0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
dac0: 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
dad0: 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
dae0: 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
daf0: 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
db00: 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
db10: 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
db20: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
db30: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
db40: 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
db50: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
db60: 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
db70: 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
db80: 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
db90: 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f   to be .** autho
dba0: 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
dbb0: 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
dbc0: 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
dbd0: 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
dbe0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  .** function wil
dbf0: 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
dc00: 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
dc10: 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
dc20: 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
dc30: 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
dc40: 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
dc50: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
dc60: 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
dc70: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
dc80: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
dc90: 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
dca0: 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20  n", "temp", .** 
dcb0: 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
dcc0: 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61  ble.  The 6th pa
dcd0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
dce0: 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
dcf0: 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
dd00: 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
dd10: 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
dd20: 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
dd30: 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
dd40: 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
dd50: 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
dd60: 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
dd70: 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
dd80: 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  m .** top-level 
dd90: 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
dda0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
ddb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
ddc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
ddd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
dde0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
ddf0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
de00: 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
de10: 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
de20: 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
de30: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
de40: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
de50: 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
de60: 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
de70: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
de80: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
de90: 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
dea0: 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
deb0: 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
dec0: 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
ded0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
dee0: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
def0: 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
df00: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
df10: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
df20: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
df30: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
df40: 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
df50: 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
df60: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
df70: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
df80: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
df90: 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
dfa0: 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
dfb0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
dfc0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
dfd0: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
dfe0: 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
dff0: 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
e000: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
e010: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e020: 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
e030: 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
e040: 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
e050: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
e060: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e070: 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
e080: 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
e090: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
e0a0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
e0b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e0c0: 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
e0d0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
e0e0: 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
e0f0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
e100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e110: 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
e120: 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
e130: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
e140: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
e150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e160: 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
e170: 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
e180: 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
e190: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
e1a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
e1b0: 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
e1c0: 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
e1d0: 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
e1e0: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
e1f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
e200: 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
e210: 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
e220: 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
e230: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
e240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
e250: 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
e260: 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
e270: 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
e280: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
e290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
e2a0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
e2b0: 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
e2c0: 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
e2d0: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
e2e0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
e2f0: 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
e300: 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
e310: 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
e320: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
e330: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
e340: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
e350: 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
e360: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
e370: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
e380: 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
e390: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
e3a0: 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
e3b0: 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
e3c0: 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
e3d0: 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
e3e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
e3f0: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
e400: 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
e410: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e420: 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
e430: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
e440: 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
e450: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
e460: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
e470: 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
e480: 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
e490: 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
e4a0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
e4b0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
e4c0: 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
e4d0: 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
e4e0: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
e4f0: 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
e500: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e510: 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
e520: 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
e530: 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
e540: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
e550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e560: 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
e570: 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
e580: 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
e590: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
e5a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e5b0: 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
e5c0: 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
e5d0: 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
e5e0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
e5f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e600: 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
e610: 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
e620: 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
e630: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
e640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e650: 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
e660: 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
e670: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
e680: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
e690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
e6a0: 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
e6b0: 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
e6c0: 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
e6d0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
e6e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
e6f0: 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
e700: 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
e710: 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
e720: 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
e730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
e740: 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
e750: 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69    31   /* Functi
e760: 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  on Name   NULL  
e770: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
e780: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
e790: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
e7a0: 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
e7b0: 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
e7c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
e7d0: 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
e7e0: 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
e7f0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
e800: 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
e810: 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
e820: 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
e830: 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
e840: 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
e850: 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
e860: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 54  statements..** T
e870: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
e880: 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
e890: 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
e8a0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
e8b0: 20 61 74 20 74 68 65 20 66 69 72 73 74 20 5b 73   at the first [s
e8c0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
e8d0: 6f 72 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  or the evaluatio
e8e0: 6e 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  n of an SQL stat
e8f0: 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61  ement..** The ca
e900: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
e910: 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
e920: 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
e930: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
e940: 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
e950: 65 6e 74 20 66 69 6e 69 73 68 65 73 20 61 6e 64  ent finishes and
e960: 20 69 6e 63 6c 75 64 65 73 0a 2a 2a 20 69 6e 66   includes.** inf
e970: 6f 72 6d 61 74 69 6f 6e 20 6f 6e 20 68 6f 77 20  ormation on how 
e980: 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
e990: 65 6e 74 20 72 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ent ran..**.** T
e9a0: 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  he sqlite3_profi
e9b0: 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72 72  le() API is curr
e9c0: 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
e9d0: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
e9e0: 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20  d.** is subject 
e9f0: 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f  to change..*/.vo
ea00: 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
ea10: 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
ea20: 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
ea30: 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
ea40: 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
ea50: 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
ea60: 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
ea70: 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
ea80: 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
ea90: 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
eaa0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
eab0: 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
eac0: 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
ead0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
eae0: 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61   configures a ca
eaf0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
eb00: 2d 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  - the progress c
eb10: 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 0a 2a  allback - that.*
eb20: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72  * is invoked per
eb30: 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
eb40: 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
eb50: 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
eb60: 65 78 65 63 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  exec()],.** [sql
eb70: 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
eb80: 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
eb90: 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
eba0: 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
ebb0: 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69   .** interface i
ebc0: 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
ebd0: 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
ebe0: 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
ebf0: 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
ec00: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
ec10: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76  oked once for ev
ec20: 65 72 79 20 4e 20 76 69 72 74 75 61 6c 20 6d 61  ery N virtual ma
ec30: 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 0a 2a  chine opcodes,.*
ec40: 2a 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  * where N is the
ec50: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
ec60: 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
ec70: 6e 2e 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  n. The progress 
ec80: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 74 73 65  callback.** itse
ec90: 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  lf is identified
eca0: 20 62 79 20 74 68 65 20 74 68 69 72 64 20 61 72   by the third ar
ecb0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66  gument to this f
ecc0: 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 66 6f 75  unction. The fou
ecd0: 72 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rth.** argument 
ece0: 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
ecf0: 20 69 73 20 61 20 76 6f 69 64 20 70 6f 69 6e 74   is a void point
ed00: 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
ed10: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
ed20: 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 65  ck.** function e
ed30: 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69  ach time it is i
ed40: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  nvoked..**.** If
ed50: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
ed60: 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
ed70: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f  lite3_step()], o
ed80: 72 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  r [sqlite3_get_t
ed90: 61 62 6c 65 28 29 5d 0a 2a 2a 20 72 65 73 75 6c  able()].** resul
eda0: 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e  ts in fewer than
edb0: 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67   N opcodes being
edc0: 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20   executed, then 
edd0: 74 68 65 20 70 72 6f 67 72 65 73 73 20 0a 2a 2a  the progress .**
ede0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76   callback is nev
edf0: 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 0a  er invoked..** .
ee00: 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  ** Only a single
ee10: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
ee20: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
ee30: 62 65 20 72 65 67 69 73 74 65 72 65 64 20 66 6f  be registered fo
ee40: 72 20 65 61 63 68 0a 2a 2a 20 6f 70 65 6e 20 64  r each.** open d
ee50: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ee60: 6f 6e 2e 20 20 45 76 65 72 79 20 63 61 6c 6c 20  on.  Every call 
ee70: 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  to sqlite3_progr
ee80: 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a  ess_handler().**
ee90: 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20   overwrites the 
eea0: 72 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 70  results of the p
eeb0: 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 0a 2a 2a  revious call..**
eec0: 20 54 6f 20 72 65 6d 6f 76 65 20 74 68 65 20 70   To remove the p
eed0: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
eee0: 20 61 6c 74 6f 67 65 74 68 65 72 2c 20 70 61 73   altogether, pas
eef0: 73 20 4e 55 4c 4c 20 61 73 20 74 68 65 20 74 68  s NULL as the th
ef00: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
ef10: 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
ef20: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70  ..**.** If the p
ef30: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
ef40: 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
ef50: 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20  t other than 0, 
ef60: 74 68 65 6e 20 74 68 65 20 63 75 72 72 65 6e 74  then the current
ef70: 20 0a 2a 2a 20 71 75 65 72 79 20 69 73 20 69 6d   .** query is im
ef80: 6d 65 64 69 61 74 65 6c 79 20 74 65 72 6d 69 6e  mediately termin
ef90: 61 74 65 64 20 61 6e 64 20 61 6e 79 20 64 61 74  ated and any dat
efa0: 61 62 61 73 65 20 63 68 61 6e 67 65 73 20 72 6f  abase changes ro
efb0: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 54 68  lled back..** Th
efc0: 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 5b 73 71  e containing [sq
efd0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
efe0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
eff0: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
f000: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 63 61 6c  get_table()] cal
f010: 6c 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  l returns SQLITE
f020: 5f 49 4e 54 45 52 52 55 50 54 2e 20 20 20 54 68  _INTERRUPT.   Th
f030: 69 73 20 66 65 61 74 75 72 65 0a 2a 2a 20 63 61  is feature.** ca
f040: 6e 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  n be used, for e
f050: 78 61 6d 70 6c 65 2c 20 74 6f 20 69 6d 70 6c 65  xample, to imple
f060: 6d 65 6e 74 20 74 68 65 20 22 43 61 6e 63 65 6c  ment the "Cancel
f070: 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 0a 2a 2a  " button on a.**
f080: 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
f090: 20 62 6f 78 20 69 6e 20 61 20 47 55 49 2e 0a 2a   box in a GUI..*
f0a0: 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
f0b0: 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
f0c0: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
f0d0: 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
f0e0: 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
f0f0: 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
f100: 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
f110: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f  nnection.**.** O
f120: 70 65 6e 20 74 68 65 20 73 71 6c 69 74 65 20 64  pen the sqlite d
f130: 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 66 69  atabase file "fi
f140: 6c 65 6e 61 6d 65 22 2e 20 20 54 68 65 20 22 66  lename".  The "f
f150: 69 6c 65 6e 61 6d 65 22 20 69 73 20 55 54 46 2d  ilename" is UTF-
f160: 38 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 66 6f 72  8.** encoded for
f170: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f180: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  ] and [sqlite3_o
f190: 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 55 54  pen_v2()] and UT
f1a0: 46 2d 31 36 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  F-16 encoded.** 
f1b0: 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
f1c0: 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71  te order for [sq
f1d0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
f1e0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a  .** An [sqlite3*
f1f0: 5d 20 68 61 6e 64 6c 65 20 69 73 20 72 65 74 75  ] handle is retu
f200: 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
f210: 76 65 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72  ven.** if an err
f220: 6f 72 20 6f 63 63 75 72 73 2e 20 49 66 20 74 68  or occurs. If th
f230: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
f240: 65 6e 65 64 20 28 6f 72 20 63 72 65 61 74 65 64  ened (or created
f250: 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 0a  ) successfully,.
f260: 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  ** then [SQLITE_
f270: 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
f280: 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   Otherwise an er
f290: 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
f2a0: 72 6e 65 64 2e 20 54 68 65 0a 2a 2a 20 5b 73 71  rned. The.** [sq
f2b0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
f2c0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
f2d0: 73 67 31 36 28 29 5d 20 20 72 6f 75 74 69 6e 65  sg16()]  routine
f2e0: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
f2f0: 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
f300: 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
f310: 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
f320: 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  e error..**.** T
f330: 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
f340: 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
f350: 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
f360: 2d 38 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  -8 if.** [sqlite
f370: 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71  3_open()] or [sq
f380: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
f390: 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
f3a0: 2a 20 55 54 46 2d 31 36 20 69 66 20 5b 73 71 6c  * UTF-16 if [sql
f3b0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
f3c0: 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68  s used..**.** Wh
f3d0: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
f3e0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
f3f0: 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
f400: 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69  resources associ
f410: 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
f420: 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64   [sqlite3*] hand
f430: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
f440: 65 61 73 65 64 20 62 79 20 70 61 73 73 69 6e 67  eased by passing
f450: 20 69 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74   it to.** [sqlit
f460: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
f470: 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
f480: 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
f490: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
f4a0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
f4b0: 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 5b 73  ce works like [s
f4c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 65  qlite3_open()] e
f4d0: 78 63 65 70 74 20 74 68 61 74 0a 2a 2a 20 70 72  xcept that.** pr
f4e0: 6f 76 69 64 65 73 20 74 77 6f 20 61 64 64 69 74  ovides two addit
f4f0: 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
f500: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
f510: 63 6f 6e 74 72 6f 6c 20 6f 76 65 72 20 74 68 65  control over the
f520: 0a 2a 2a 20 6e 65 77 20 64 61 74 61 62 61 73 65  .** new database
f530: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
f540: 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
f550: 72 20 63 61 6e 20 62 65 20 6f 6e 65 20 6f 66 3a  r can be one of:
f560: 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
f570: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
f580: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c  N_READONLY].** <
f590: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
f5a0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a 2a 20  N_READWRITE].** 
f5b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
f5c0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
f5d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
f5e0: 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ATE].** </ol>.**
f5f0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 76 61  .** The first va
f600: 6c 75 65 20 6f 70 65 6e 73 20 74 68 65 20 64 61  lue opens the da
f610: 74 61 62 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79  tabase read-only
f620: 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
f630: 73 65 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 70  se does.** not p
f640: 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c  reviously exist,
f650: 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
f660: 75 72 6e 65 64 2e 20 20 54 68 65 20 73 65 63 6f  urned.  The seco
f670: 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a  nd option opens.
f680: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
f690: 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
f6a0: 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
f6b0: 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 20  ble, or reading 
f6c0: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69 66 20 74 68  only if.** if th
f6d0: 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
f6e0: 70 72 6f 74 65 63 74 65 64 2e 20 20 49 6e 20 65  protected.  In e
f6f0: 69 74 68 65 72 20 63 61 73 65 20 74 68 65 20 64  ither case the d
f700: 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
f710: 65 61 64 79 0a 2a 2a 20 65 78 69 73 74 20 6f 72  eady.** exist or
f720: 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
f730: 75 72 6e 65 64 2e 20 20 54 68 65 20 74 68 69 72  urned.  The thir
f740: 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 20 74  d option opens t
f750: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
f760: 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
f770: 72 69 74 69 6e 67 20 61 6e 64 20 63 72 65 61 74  riting and creat
f780: 65 73 20 69 74 20 69 66 20 69 74 20 64 6f 65 73  es it if it does
f790: 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
f7a0: 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  st..** The third
f7b0: 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 65 68 61   options is beha
f7c0: 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
f7d0: 61 79 73 20 75 73 65 64 20 66 6f 72 20 5b 73 71  ays used for [sq
f7e0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
f7f0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
f800: 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  en16()]..**.** I
f810: 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
f820: 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
f830: 65 6e 20 61 6e 20 70 72 69 76 61 74 65 0a 2a 2a  en an private.**
f840: 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
f850: 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66  ase is created f
f860: 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
f870: 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  n.  This in-memo
f880: 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 77  ry.** database w
f890: 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 20  ill vanish when 
f8a0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
f8b0: 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
f8c0: 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
f8d0: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
f8e0: 6d 69 67 68 74 20 6d 61 6b 65 20 75 73 65 20 6f  might make use o
f8f0: 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
f900: 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a  cial filenames.*
f910: 2a 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  * that begin wit
f920: 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
f930: 74 65 72 2e 20 20 49 74 20 69 73 20 72 65 63 6f  ter.  It is reco
f940: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 0a 2a 2a  mmended that .**
f950: 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
f960: 20 66 69 6c 65 6e 61 6d 65 20 72 65 61 6c 6c 79   filename really
f970: 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
f980: 0a 2a 2a 20 22 3a 22 20 74 68 61 74 20 79 6f 75  .** ":" that you
f990: 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
f9a0: 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
f9b0: 6e 61 6d 65 20 6c 69 6b 65 20 22 2e 2f 22 20 74  name like "./" t
f9c0: 6f 0a 2a 2a 20 61 76 6f 69 64 20 61 6d 62 69 67  o.** avoid ambig
f9d0: 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
f9e0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
f9f0: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
fa00: 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 20 74  then a private t
fa10: 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
fa20: 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
fa30: 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54  l be created.  T
fa40: 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
fa50: 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
fa60: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
fa70: 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
fa80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
fa90: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
faa0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ed..**.** The fo
fab0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
fac0: 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
fad0: 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
fae0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
faf0: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
fb00: 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
fb10: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
fb20: 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74   .** interface t
fb30: 68 61 74 20 74 68 65 20 6e 65 77 20 64 61 74 61  hat the new data
fb40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
fb50: 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
fb60: 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
fb70: 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e 55 4c  rameter is a NUL
fb80: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
fb90: 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
fba0: 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a 65  te3_vfs].** obje
fbb0: 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
fbc0: 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 77 69 6e  * <b>Note to win
fbd0: 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
fbe0: 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
fbf0: 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
fc00: 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
fc10: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  of [sqlite3_open
fc20: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
fc30: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75 73 74  _open_v2()] must
fc40: 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
fc50: 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
fc60: 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
fc70: 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
fc80: 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
fc90: 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
fca0: 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
fcb0: 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
fcc0: 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
fcd0: 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
fce0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  o.** [sqlite3_op
fcf0: 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  en()] or [sqlite
fd00: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  3_open_v2()]..*/
fd10: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
fd20: 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
fd30: 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
fd40: 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
fd50: 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
fd60: 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
fd70: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
fd80: 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
fd90: 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
fda0: 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
fdb0: 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
fdc0: 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
fdd0: 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
fde0: 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
fdf0: 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
fe00: 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
fe10: 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
fe20: 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
fe30: 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
fe40: 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
fe50: 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
fe60: 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
fe70: 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
fe80: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
fe90: 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
fea0: 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
feb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
fec0: 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
fed0: 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
fee0: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
fef0: 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
ff00: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
ff10: 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
ff20: 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
ff30: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ff40: 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
ff50: 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
ff60: 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51  e numeric.** [SQ
ff70: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
ff80: 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54   code] or [SQLIT
ff90: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
ffa0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
ffb0: 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ode].** for the 
ffc0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
ffd0: 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
ffe0: 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
fff0: 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74 65  .** with [sqlite
10000 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e 20  3] handle 'db'. 
10010 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
10020 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20  call failed but 
10030 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
10040 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
10050 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
10060 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
10070 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a  ite3_errcode().*
10080 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  * is undefined. 
10090 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
100a0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
100b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
100c0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
100d0 68 2d 6c 61 6e 67 61 75 67 65 0a 2a 2a 20 74 65  h-langauge.** te
100e0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
100f0 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
10100 65 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55  either UTF8 or U
10110 54 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  TF16 respectivel
10120 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20  y..** Memory to 
10130 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
10140 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
10150 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
10160 6c 6c 79 2e 20 20 54 68 65 20 0a 2a 2a 20 73 74  lly.  The .** st
10170 72 69 6e 67 20 6d 61 79 20 62 65 20 6f 76 65 72  ring may be over
10180 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
10190 6f 63 61 74 65 64 20 62 79 20 73 75 62 73 65 71  ocated by subseq
101a0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 53 51  uent calls to SQ
101b0 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  Lite.** interfac
101c0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  e functions..**.
101d0 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 6d 61 6e 79  ** Calls to many
101e0 20 73 71 6c 69 74 65 33 5f 2a 20 66 75 6e 63 74   sqlite3_* funct
101f0 69 6f 6e 73 20 73 65 74 20 74 68 65 20 65 72 72  ions set the err
10200 6f 72 20 63 6f 64 65 20 61 6e 64 20 73 74 72 69  or code and stri
10210 6e 67 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ng returned.** b
10220 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  y [sqlite3_errco
10230 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
10240 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b  errmsg()], and [
10250 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
10260 28 29 5d 0a 2a 2a 20 28 6f 76 65 72 77 72 69 74  ()].** (overwrit
10270 69 6e 67 20 74 68 65 20 70 72 65 76 69 6f 75 73  ing the previous
10280 20 76 61 6c 75 65 73 29 2e 20 4e 6f 74 65 20 74   values). Note t
10290 68 61 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hat calls to [sq
102a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
102b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  ,.** [sqlite3_er
102c0 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
102d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
102e0 5d 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  ] themselves do 
102f0 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 0a 2a  not affect the.*
10300 2a 20 72 65 73 75 6c 74 73 20 6f 66 20 66 75 74  * results of fut
10310 75 72 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e  ure invocations.
10320 20 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72    Calls to API r
10330 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20  outines that do 
10340 6e 6f 74 20 72 65 74 75 72 6e 0a 2a 2a 20 61 6e  not return.** an
10350 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61   error code (exa
10360 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64  mple: [sqlite3_d
10370 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f  ata_count()]) do
10380 20 6e 6f 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74   not.** change t
10390 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 72 65  he error code re
103a0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
103b0 6f 75 74 69 6e 65 2e 20 20 49 6e 74 65 72 66 61  outine.  Interfa
103c0 63 65 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ces that are.** 
103d0 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  not associated w
103e0 69 74 68 20 61 20 73 70 65 63 69 66 69 63 20 64  ith a specific d
103f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10400 6f 6e 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a  on (examples:.**
10410 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
10420 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  f()] or [sqlite3
10430 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
10440 61 63 68 65 28 29 5d 20 64 6f 20 6e 6f 74 20 63  ache()] do not c
10450 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
10460 75 72 6e 20 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a  urn code.  .**.*
10470 2a 20 41 73 73 75 6d 69 6e 67 20 6e 6f 20 6f 74  * Assuming no ot
10480 68 65 72 20 69 6e 74 65 72 76 65 6e 69 6e 67 20  her intervening 
10490 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
104a0 6c 6c 73 20 61 72 65 20 6d 61 64 65 2c 20 74 68  lls are made, th
104b0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
104c0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
104d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 73 73   function is ass
104e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
104f0 20 73 61 6d 65 20 65 72 72 6f 72 20 61 73 0a 2a   same error as.*
10500 2a 20 74 68 65 20 73 74 72 69 6e 67 73 20 72 65  * the strings re
10510 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
10520 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
10530 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
10540 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
10550 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
10560 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
10570 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
10580 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
10590 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
105a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
105b0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
105c0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
105d0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
105e0 2a 2a 0a 2a 2a 20 49 6e 73 74 61 6e 63 65 20 6f  **.** Instance o
105f0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
10600 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65 20 53  present single S
10610 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
10620 54 68 69 73 0a 2a 2a 20 69 73 20 76 61 72 69 6f  This.** is vario
10630 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
10640 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
10650 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63  ent" or a .** "c
10660 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
10670 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
10680 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
10690 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69  "..** .** The li
106a0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
106b0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
106c0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
106d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
106e0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
106f0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
10700 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
10710 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
10720 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
10730 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
10740 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
10750 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e 67  parameters using
10760 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
10770 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
10780 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74  lite3_bind_* int
10790 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69  erfaces]..** <li
107a0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
107b0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
107c0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
107d0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
107e0 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
107f0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
10800 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
10810 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
10820 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
10830 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
10840 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
10850 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
10860 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
10870 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
10880 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
10890 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
108a0 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
108b0 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
108c0 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
108d0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
108e0 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
108f0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
10900 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
10910 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
10920 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
10930 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
10940 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
10950 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
10960 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
10970 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
10980 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
10990 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
109a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
109b0 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73   .**.** The firs
109c0 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22 20  t argument "db" 
109d0 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 20 7c  is an [sqlite3 |
109e0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
109f0 20 68 61 6e 64 6c 65 5d 20 0a 2a 2a 20 6f 62 74   handle] .** obt
10a00 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
10a10 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  or call to [sqli
10a20 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
10a30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
10a40 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
10a50 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 54 68  open16()]..** Th
10a60 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
10a70 74 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20  t "zSql" is the 
10a80 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
10a90 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
10aa0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
10ab0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
10ac0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
10ad0 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
10ae0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
10af0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
10b00 65 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c  es UTF-8 and sql
10b10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
10b20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
10b30 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
10b40 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
10b50 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
10b60 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a 2a  gument is less.*
10b70 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  * than zero, the
10b80 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
10b90 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
10ba0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
10bb0 20 49 66 0a 2a 2a 20 6e 42 79 74 65 20 69 73 20   If.** nByte is 
10bc0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
10bd0 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
10be0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 0a  imum number of .
10bf0 2a 2a 20 62 79 74 65 73 20 72 65 61 64 20 66 72  ** bytes read fr
10c00 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e  om zSql.  When n
10c10 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
10c20 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
10c30 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
10c40 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
10c50 74 20 27 5c 30 30 30 27 20 63 68 61 72 61 63 74  t '\000' charact
10c60 65 72 20 6f 72 20 0a 2a 2a 20 75 6e 74 69 6c 20  er or .** until 
10c70 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
10c80 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
10c90 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
10ca0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
10cb0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
10cc0 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
10cd0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
10ce0 69 72 73 74 0a 2a 2a 20 53 51 4c 20 73 74 61 74  irst.** SQL stat
10cf0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
10d00 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
10d10 79 20 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66  y compiles the f
10d20 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 0a 2a  irst statement.*
10d30 2a 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  * in zSql, so *p
10d40 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
10d50 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72  inting to what r
10d60 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
10d70 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74  d..**.** *ppStmt
10d80 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
10d90 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
10da0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
10db0 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  t | SQL statemen
10dc0 74 20 73 74 72 75 63 74 75 72 65 5d 20 74 68 61  t structure] tha
10dd0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
10de0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
10df0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72  te3_step()].  Or
10e00 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
10e10 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 6d  error, *ppStmt m
10e20 61 79 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f 20  ay be.** set to 
10e30 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e  NULL.  If the in
10e40 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
10e50 65 64 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ed no SQL (if th
10e60 65 20 69 6e 70 75 74 20 69 73 20 61 6e 64 0a 2a  e input is and.*
10e70 2a 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  * empty string o
10e80 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
10e90 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
10ea0 20 74 6f 20 4e 55 4c 4c 2e 20 20 54 68 65 20 63   to NULL.  The c
10eb0 61 6c 6c 69 6e 67 0a 2a 2a 20 70 72 6f 63 65 64  alling.** proced
10ec0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
10ed0 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
10ee0 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  the compiled SQL
10ef0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73   statement.** us
10f00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
10f10 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
10f20 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
10f30 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ith it..**.** On
10f40 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
10f50 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
10f60 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
10f70 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
10f80 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d  OR | error code]
10f90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
10fa0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10fb0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
10fc0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
10fd0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
10fe0 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
10ff0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
11000 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
11010 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
11020 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
11030 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
11040 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
11050 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
11060 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
11070 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  ** In the "v2" i
11080 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
11090 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
110a0 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
110b0 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
110c0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
110d0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
110e0 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69  y of the .** ori
110f0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
11100 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
11110 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
11120 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
11130 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72   behave a differ
11140 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79  ently in two way
11150 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
11160 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20   <li>.** If the 
11170 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
11180 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
11190 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
111a0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
111b0 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
111c0 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
111d0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
111e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
111f0 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
11200 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
11210 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
11220 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63  gain.  If the sc
11230 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64  hema has changed
11240 20 69 6e 20 61 20 77 61 79 0a 2a 2a 20 74 68 61   in a way.** tha
11250 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74  t makes the stat
11260 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20  ement no longer 
11270 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f  valid, [sqlite3_
11280 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69  step()] will sti
11290 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
112a0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42  LITE_SCHEMA].  B
112b0 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65  ut unlike the le
112c0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b  gacy behavior, [
112d0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69  SQLITE_SCHEMA] i
112e0 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c  s.** now a fatal
112f0 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67   error.  Calling
11300 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
11310 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69  e_v2()] again wi
11320 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a  ll not make the.
11330 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79  ** error go away
11340 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71  .  Note: use [sq
11350 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
11360 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74  to find the text
11370 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 0a   of the parsing.
11380 2a 2a 20 65 72 72 6f 72 20 74 68 61 74 20 72 65  ** error that re
11390 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c  sults in an [SQL
113a0 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75  ITE_SCHEMA] retu
113b0 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  rn..** </li>.**.
113c0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20  ** <li>.** When 
113d0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
113e0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
113f0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
11400 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
11410 61 69 6c 65 64 20 0a 2a 2a 20 5b 53 51 4c 49 54  ailed .** [SQLIT
11420 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74  E_ERROR | result
11430 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 53   codes] or.** [S
11440 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
11450 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
11460 6c 74 20 63 6f 64 65 73 5d 20 73 75 63 68 20 61  lt codes] such a
11470 73 20 64 69 72 65 63 74 6c 79 2e 0a 2a 2a 20 54  s directly..** T
11480 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
11490 6f 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c  or was that [sql
114a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
114b0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
114c0 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c   generic.** [SQL
114d0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
114e0 74 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77  t code and you w
114f0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
11500 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
11510 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
11520 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72  eset()] in order
11530 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
11540 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
11550 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a   the problem..**
11560 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
11570 72 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65  repare interface
11580 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
11590 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
115a0 20 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74   error is.** ret
115b0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
115c0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  y..** </li>.** <
115d0 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
115e0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
115f0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
11600 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
11610 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
11620 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
11630 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
11640 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
11650 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
11660 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
11670 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
11680 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
11690 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
116a0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
116b0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
116c0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
116d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
116e0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
116f0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
11700 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
11710 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
11720 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
11730 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
11740 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
11750 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
11760 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
11770 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
11780 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
11790 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
117a0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
117b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
117c0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
117d0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
117e0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
117f0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
11800 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
11810 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
11820 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
11830 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
11840 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
11850 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
11860 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
11870 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
11880 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
11890 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
118a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
118b0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
118c0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
118d0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
118e0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
118f0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
11900 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
11910 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
11920 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
11930 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
11940 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
11950 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
11960 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
11970 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
11980 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
11990 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
119a0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
119b0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
119c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
119d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
119e0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
119f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
11a00 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
11a10 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
11a20 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
11a30 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
11a40 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
11a50 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
11a60 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
11a70 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
11a80 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
11a90 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
11aa0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
11ab0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
11ac0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
11ad0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
11ae0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
11af0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11b00 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79    Dynamically Ty
11b10 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
11b20 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
11b30 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
11b40 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  g for the values
11b50 20 69 74 20 73 74 6f 72 65 73 2e 20 20 56 61 6c   it stores.  Val
11b60 75 65 73 20 63 61 6e 20 0a 2a 2a 20 62 65 20 69  ues can .** be i
11b70 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
11b80 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
11b90 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
11ba0 6f 72 20 4e 55 4c 4c 2e 20 20 57 68 65 6e 0a 2a  or NULL.  When.*
11bb0 2a 20 70 61 73 73 69 6e 67 20 61 72 6f 75 6e 64  * passing around
11bc0 20 76 61 6c 75 65 73 20 69 6e 74 65 72 6e 61 6c   values internal
11bd0 6c 79 2c 20 65 61 63 68 20 76 61 6c 75 65 20 69  ly, each value i
11be0 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
11bf0 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  .** an instance 
11c00 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
11c10 61 6c 75 65 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  alue object..*/.
11c20 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
11c30 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
11c40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11c50 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  F:  SQL Function
11c60 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
11c70 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
11c80 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
11c90 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
11ca0 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
11cb0 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
11cc0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
11cd0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 75 63  A pointer to suc
11ce0 68 20 61 6e 20 6f 62 6a 65 63 74 20 69 73 20 74  h an object is t
11cf0 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61  he.** first para
11d00 6d 65 74 65 72 20 74 6f 20 75 73 65 72 2d 64 65  meter to user-de
11d10 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
11d20 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ons..*/.typedef 
11d30 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
11d40 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
11d50 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
11d60 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e  API3REF:  Bindin
11d70 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
11d80 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
11d90 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c  **.** In the SQL
11da0 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74   strings input t
11db0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
11dc0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
11dd0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6f 6e   variants,.** on
11de0 65 20 6f 72 20 6d 6f 72 65 20 6c 69 74 65 72 61  e or more litera
11df0 6c 73 20 63 61 6e 20 62 65 20 72 65 70 6c 61 63  ls can be replac
11e00 65 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72  e by a parameter
11e10 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   in one of these
11e20 0a 2a 2a 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a  .** forms:.**.**
11e30 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
11e40 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
11e50 2a 20 3c 6c 69 3e 20 20 3a 41 41 41 0a 2a 2a 20  * <li>  :AAA.** 
11e60 3c 6c 69 3e 20 20 40 41 41 41 0a 2a 2a 20 3c 6c  <li>  @AAA.** <l
11e70 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
11e80 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70  >.**.** In the p
11e90 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73  arameter forms s
11ea0 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69  hown above NNN i
11eb0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
11ec0 65 72 61 6c 2c 0a 2a 2a 20 41 41 41 20 69 73 20  eral,.** AAA is 
11ed0 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
11ee0 69 64 65 6e 74 69 66 69 65 72 20 61 6e 64 20 56  identifier and V
11ef0 56 56 20 69 73 20 61 20 76 61 72 69 61 62 6c 65  VV is a variable
11f00 20 6e 61 6d 65 20 61 63 63 6f 72 64 69 6e 67 0a   name according.
11f10 2a 2a 20 74 6f 20 74 68 65 20 73 79 6e 74 61 78  ** to the syntax
11f20 20 72 75 6c 65 73 20 6f 66 20 74 68 65 20 54 43   rules of the TC
11f30 4c 20 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61  L programming la
11f40 6e 67 75 61 67 65 2e 0a 2a 2a 20 54 68 65 20 76  nguage..** The v
11f50 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20 70  alues of these p
11f60 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
11f70 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
11f80 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 29 0a 2a  ameter names").*
11f90 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
11fa0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
11fb0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
11fc0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
11fd0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
11fe0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
11ff0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
12000 72 6f 75 74 69 6e 65 73 20 61 6c 77 61 79 73 20  routines always 
12010 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
12020 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
12030 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
12040 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
12050 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
12060 5d 20 6f 72 0a 2a 2a 20 69 74 73 20 76 61 72 69  ] or.** its vari
12070 61 6e 74 73 2e 20 20 54 68 65 20 73 65 63 6f 6e  ants.  The secon
12080 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  d.** argument is
12090 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
120a0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  e parameter to b
120b0 65 20 73 65 74 2e 20 20 54 68 65 20 66 69 72 73  e set.  The firs
120c0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 0a  t parameter has.
120d0 2a 2a 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  ** an index of 1
120e0 2e 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20  . When the same 
120f0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
12100 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
12110 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 0a 2a  n once, second.*
12120 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  * and subsequent
12130 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
12140 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
12150 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
12160 20 6f 63 63 75 72 72 65 6e 63 65 2e 20 20 54 68   occurrence.  Th
12170 65 20 69 6e 64 65 78 20 66 6f 72 0a 2a 2a 20 6e  e index for.** n
12180 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
12190 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
121a0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
121b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
121c0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50  meter_name()] AP
121d0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54  I if desired.  T
121e0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 22 3f 4e  he index for "?N
121f0 4e 4e 22 0a 2a 2a 20 70 61 72 61 6d 65 74 65 73  NN".** parametes
12200 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
12210 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e   NNN..** The NNN
12220 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
12230 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
12240 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
12250 20 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54   parameter SQLIT
12260 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e  E_MAX_VARIABLE_N
12270 55 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20 76  UMBER (default v
12280 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 20 53  alue: 999)..** S
12290 65 65 20 3c 61 20 68 72 65 66 3d 22 6c 69 6d 69  ee <a href="limi
122a0 74 73 2e 68 74 6d 6c 22 3e 6c 69 6d 69 74 73 2e  ts.html">limits.
122b0 68 74 6d 6c 3c 2f 61 3e 20 66 6f 72 20 61 64 64  html</a> for add
122c0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
122d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ion..**.** The t
122e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
122f0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
12300 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
12310 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ter..**.** In th
12320 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ose.** routines 
12330 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
12340 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
12350 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75   value is the nu
12360 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
12370 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
12380 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
12390 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
123a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
123b0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 73 74 72 69  s in the.** stri
123c0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
123d0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
123e0 2e 20 20 54 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  .  The number.**
123f0 20 6f 66 20 62 79 74 65 73 20 64 6f 65 73 20 6e   of bytes does n
12400 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
12410 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 61  ero-terminator a
12420 74 20 74 68 65 20 65 6e 64 20 6f 66 20 73 74 72  t the end of str
12430 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ings..** If the 
12440 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
12450 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
12460 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
12470 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75 6d  string is.** num
12480 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
12490 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
124a0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
124b0 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72  .** The fifth ar
124c0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
124d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
124e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
124f0 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
12500 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
12510 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
12520 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
12530 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
12540 2a 2a 20 74 65 78 74 20 61 66 74 65 72 20 53 51  ** text after SQ
12550 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
12560 64 20 77 69 74 68 20 69 74 2e 20 20 49 66 20 74  d with it.  If t
12570 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
12580 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 70 65 63  t is the.** spec
12590 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
125a0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
125b0 74 68 65 20 6c 69 62 72 61 72 79 20 61 73 73 75  the library assu
125c0 6d 65 73 20 74 68 61 74 20 74 68 65 20 69 6e 66  mes that the inf
125d0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  ormation.** is i
125e0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
125f0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
12600 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
12610 65 20 66 72 65 65 64 2e 20 20 49 66 20 74 68 65  e freed.  If the
12620 0a 2a 2a 20 66 69 66 74 68 20 61 72 67 75 6d 65  .** fifth argume
12630 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
12640 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
12650 4e 54 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  NT], then SQLite
12660 20 6d 61 6b 65 73 20 69 74 73 0a 2a 2a 20 6f 77   makes its.** ow
12670 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
12680 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
12690 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74  iately, before t
126a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
126b0 2a 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  *().** routine r
126c0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  eturns..**.** Th
126d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
126e0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
126f0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
12700 66 20 6c 65 6e 67 74 68 20 6e 20 74 68 61 74 0a  f length n that.
12710 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
12720 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f  h zeros.  A zero
12730 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
12740 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
12750 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
12760 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
12770 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  t size) while it
12780 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
12790 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
127a0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
127b0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
127c0 2d 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  -holders for BLO
127d0 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
127e0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
127f0 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  tten using .** [
12800 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
12810 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c  n | increment BL
12820 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
12830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
12840 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
12850 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
12860 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73  lled after.** [s
12870 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
12880 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61  2()] (and its va
12890 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69  riants) or [sqli
128a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64  te3_reset()] and
128b0 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69  .** before [sqli
128c0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
128d0 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
128e0 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
128f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
12900 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e  ] routine..** Un
12910 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
12920 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
12930 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
12940 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
12950 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
12960 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
12970 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66  an error code if
12980 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65  .** anything goe
12990 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54  s wrong.  [SQLIT
129a0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
129b0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
129c0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
129d0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
129e0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
129f0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
12a00 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20  alloc fails..** 
12a10 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
12a20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
12a30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
12a40 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 76 69  e called on a vi
12a50 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
12a60 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f   that is the wro
12a70 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63  ng state or whic
12a80 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65  h has already be
12a90 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f  en finalized..*/
12aa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
12ab0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
12ac0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
12ad0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
12ae0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
12af0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
12b00 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
12b10 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
12b20 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
12b30 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
12b40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
12b50 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
12b60 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
12b70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
12b80 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
12b90 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
12ba0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
12bb0 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
12bc0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
12bd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
12be0 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
12bf0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
12c00 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
12c10 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
12c20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
12c30 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
12c40 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
12c50 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
12c60 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
12c70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
12c80 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
12c90 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
12ca0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
12cb0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
12cc0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
12cd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12ce0 20 4e 75 6d 62 65 72 20 4f 66 20 48 6f 73 74 20   Number Of Host 
12cf0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
12d00 20 52 65 74 75 72 6e 20 74 68 65 20 6c 61 72 67   Return the larg
12d10 65 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  est host paramet
12d20 65 72 20 69 6e 64 65 78 20 69 6e 20 74 68 65 20  er index in the 
12d30 70 72 65 63 6f 6d 70 69 6c 65 64 20 73 74 61 74  precompiled stat
12d40 65 6d 65 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 61  ement given.** a
12d50 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 2e 20  s the argument. 
12d60 20 57 68 65 6e 20 74 68 65 20 68 6f 73 74 20 70   When the host p
12d70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 6f 66  arameters are of
12d80 20 74 68 65 20 66 6f 72 6d 73 20 6c 69 6b 65 20   the forms like 
12d90 22 3a 41 41 41 22 0a 2a 2a 20 6f 72 20 22 3f 22  ":AAA".** or "?"
12da0 2c 20 74 68 65 6e 20 74 68 65 79 20 61 72 65 20  , then they are 
12db0 61 73 73 69 67 6e 65 64 20 73 65 71 75 65 6e 74  assigned sequent
12dc0 69 61 6c 20 69 6e 63 72 65 61 73 69 6e 67 20 6e  ial increasing n
12dd0 75 6d 62 65 72 73 20 62 65 67 69 6e 6e 69 6e 67  umbers beginning
12de0 0a 2a 2a 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f  .** with one, so
12df0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
12e00 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
12e10 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 2e  r of parameters.
12e20 20 20 48 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20    However.** if 
12e30 74 68 65 20 73 61 6d 65 20 68 6f 73 74 20 70 61  the same host pa
12e40 72 61 6d 65 74 65 72 20 6e 61 6d 65 20 69 73 20  rameter name is 
12e50 75 73 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  used multiple ti
12e60 6d 65 73 2c 20 65 61 63 68 20 6f 63 63 75 72 72  mes, each occurr
12e70 61 6e 63 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e  ance.** is given
12e80 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72   the same number
12e90 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72  , so the value r
12ea0 65 74 75 72 6e 65 64 20 69 6e 20 74 68 61 74 20  eturned in that 
12eb0 63 61 73 65 20 69 73 20 74 68 65 20 6e 75 6d 62  case is the numb
12ec0 65 72 0a 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20  er.** of unique 
12ed0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
12ee0 61 6d 65 73 2e 20 20 49 66 20 68 6f 73 74 20 70  ames.  If host p
12ef0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
12f00 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20   form "?NNN".** 
12f10 61 72 65 20 75 73 65 64 20 28 77 68 65 72 65 20  are used (where 
12f20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65  NNN is an intege
12f30 72 29 20 74 68 65 6e 20 74 68 65 72 65 20 6d 69  r) then there mi
12f40 67 68 74 20 62 65 20 67 61 70 73 20 69 6e 20 74  ght be gaps in t
12f50 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 69 6e 67 20  he.** numbering 
12f60 61 6e 64 20 74 68 65 20 76 61 6c 75 65 20 72 65  and the value re
12f70 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 69  turned by this i
12f80 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
12f90 69 6e 64 65 78 20 6f 66 20 74 68 65 0a 2a 2a 20  index of the.** 
12fa0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 77  host parameter w
12fb0 69 74 68 20 74 68 65 20 6c 61 72 67 65 73 74 20  ith the largest 
12fc0 69 6e 64 65 78 20 76 61 6c 75 65 2e 0a 2a 2a 0a  index value..**.
12fd0 2a 2a 20 54 68 65 20 70 72 65 70 61 72 65 64 20  ** The prepared 
12fe0 73 74 61 74 65 6d 65 6e 74 20 6d 75 73 74 20 6e  statement must n
12ff0 6f 74 20 62 65 20 5b 73 71 6c 69 74 65 33 5f 66  ot be [sqlite3_f
13000 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
13010 7a 65 64 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  zed].** prior to
13020 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
13030 74 75 72 6e 6e 69 6e 67 2e 20 20 4f 74 68 65 72  turnning.  Other
13040 77 69 73 65 20 74 68 65 20 72 65 73 75 6c 74 73  wise the results
13050 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a   are undefined.*
13060 2a 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  * and probably u
13070 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 69  ndesirable..*/.i
13080 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
13090 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
130a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
130b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
130c0 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
130d0 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
130e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
130f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
13100 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  o the name of th
13110 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
13120 20 69 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74   in a .** [sqlit
13130 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
13140 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
13150 2a 20 48 6f 73 74 20 70 61 72 61 6d 65 74 65 72  * Host parameter
13160 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a  s of the form ":
13170 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
13180 72 20 22 24 56 56 56 22 20 68 61 76 65 20 61 20  r "$VVV" have a 
13190 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73  name.** which is
131a0 20 74 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41   the string ":AA
131b0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
131c0 22 24 56 56 56 22 2e 20 20 0a 2a 2a 20 49 6e 20  "$VVV".  .** In 
131d0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
131e0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
131f0 22 24 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73  "$" or "@".** is
13200 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
13210 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  t of the name..*
13220 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20  * Parameters of 
13230 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20  the form "?" or 
13240 22 3f 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e  "?NNN" have no n
13250 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ame..**.** The f
13260 69 72 73 74 20 62 6f 75 6e 64 20 70 61 72 61 6d  irst bound param
13270 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
13280 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
13290 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75  *.** If the valu
132a0 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e n is out of ra
132b0 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d  nge or if the n-
132c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
132d0 6e 61 6d 65 6c 65 73 73 2c 0a 2a 2a 20 74 68 65  nameless,.** the
132e0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
132f0 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65  ed.  The returne
13300 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
13310 79 73 20 69 6e 20 74 68 65 0a 2a 2a 20 55 54 46  ys in the.** UTF
13320 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
13330 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
13340 72 61 6d 65 74 65 72 20 77 61 73 20 6f 72 69 67  rameter was orig
13350 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
13360 0a 2a 2a 20 61 73 20 55 54 46 2d 31 36 20 69 6e  .** as UTF-16 in
13370 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
13380 65 31 36 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  e16()] or [sqlit
13390 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
133a0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
133b0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
133c0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
133d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
133e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
133f0 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
13400 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
13410 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
13420 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
13430 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
13440 20 6f 66 20 61 20 68 6f 73 74 20 70 61 72 61 6d   of a host param
13450 65 74 65 72 20 77 69 74 68 20 74 68 65 20 67 69  eter with the gi
13460 76 65 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65  ven name..** The
13470 20 6e 61 6d 65 20 6d 75 73 74 20 6d 61 74 63 68   name must match
13480 20 65 78 61 63 74 6c 79 2e 20 20 49 66 20 6e 6f   exactly.  If no
13490 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
134a0 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 20 69  the given name i
134b0 73 20 0a 2a 2a 20 66 6f 75 6e 64 2c 20 72 65 74  s .** found, ret
134c0 75 72 6e 20 30 2e 20 20 50 61 72 61 6d 65 74 65  urn 0.  Paramete
134d0 72 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  r names must be 
134e0 55 54 46 38 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  UTF8..*/.int sql
134f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
13500 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
13510 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
13520 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
13530 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
13540 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
13550 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
13560 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 43  tatement.**.** C
13570 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
13580 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
13590 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
135a0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ()] does not.** 
135b0 72 65 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74  reset the [sqlit
135c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
135d0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a  indings] on a .*
135e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
135f0 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
13600 6d 65 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73  ment].  Use this
13610 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72   routine to.** r
13620 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
13630 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
13640 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
13650 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
13660 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
13670 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13680 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
13690 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
136a0 65 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  et.**.** Return 
136b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
136c0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
136d0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
136e0 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   by the .** [sql
136f0 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70  ite3_stmt | comp
13700 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
13710 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  nt]. This routin
13720 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69  e returns 0.** i
13730 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
13740 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
13750 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
13760 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65   data (for .** e
13770 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45  xample an UPDATE
13780 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
13790 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
137a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
137b0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
137c0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
137d0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
137e0 65 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  et.**.** These r
137f0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
13800 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
13810 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
13820 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
13830 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
13840 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
13850 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  nt.  The sqlite3
13860 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
13870 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
13880 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
13890 20 61 20 55 54 46 38 20 73 74 72 69 6e 67 20 61   a UTF8 string a
138a0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
138b0 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 72 65  n_name16().** re
138c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
138d0 74 6f 20 61 20 55 54 46 31 36 20 73 74 72 69 6e  to a UTF16 strin
138e0 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  g.  The first pa
138f0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
13900 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
13910 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
13920 6d 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c 65  ment] that imple
13930 6d 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54  ments the SELECT
13940 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
13950 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13960 74 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75 6d  ter is the colum
13970 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c  n number.  The l
13980 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
13990 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a  is.** number 0..
139a0 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  **.** The return
139b0 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
139c0 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
139d0 20 65 69 74 68 65 72 20 74 68 65 20 0a 2a 2a 20   either the .** 
139e0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
139f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13a00 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
13a10 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
13a20 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75  alize()].** or u
13a30 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
13a40 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
13a50 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
13a60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
13a70 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  6().** on the sa
13a80 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
13a90 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
13aa0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
13ab0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
13ac0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
13ad0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
13ae0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
13af0 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
13b00 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
13b10 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
13b20 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
13b30 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
13b40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
13b50 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
13b60 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
13b70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
13b80 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
13b90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
13ba0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
13bb0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
13bc0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
13bd0 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73  esult.**.** Thes
13be0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
13bf0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
13c00 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c  termine what col
13c10 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74  umn of what.** t
13c20 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61  able in which da
13c30 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20  tabase a result 
13c40 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  of a SELECT stat
13c50 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d  ement comes from
13c60 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  ..** The name of
13c70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
13c80 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
13c90 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
13ca0 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
13cb0 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 73 74  UTF8 or UTF16 st
13cc0 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61  ring.  The _data
13cd0 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
13ce0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
13cf0 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
13d00 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
13d10 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
13d20 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
13d30 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
13d40 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
13d50 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  olumn name..** T
13d60 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
13d70 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
13d80 6c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  l.** the [sqlite
13d90 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  3_stmt | prepare
13da0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
13db0 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
13dc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
13dd0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
13de0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
13df0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
13e00 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
13e10 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
13e20 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ing..**.** The n
13e30 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
13e40 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
13e50 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
13e60 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
13e70 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
13e80 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  olumn..**.** The
13e90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13ea0 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  to the following
13eb0 20 63 61 6c 6c 73 20 69 73 20 61 20 0a 2a 2a 20   calls is a .** 
13ec0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
13ed0 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
13ee0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73  tement]..** Thes
13ef0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
13f00 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
13f10 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c  bout the Nth col
13f20 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
13f30 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
13f40 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
13f50 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
13f60 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
13f70 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  * If the Nth col
13f80 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
13f90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
13fa0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a   an expression.*
13fb0 2a 20 6f 72 20 73 75 62 71 75 65 72 79 20 61 6e  * or subquery an
13fc0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
13fd0 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
13fe0 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
13ff0 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e  ions.** return N
14000 55 4c 4c 2e 20 4f 74 68 65 72 77 69 73 65 2c 20  ULL. Otherwise, 
14010 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
14020 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
14030 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
14040 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  e, table and col
14050 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
14060 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
14070 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
14080 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74  om..**.** As wit
14090 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
140a0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70  te APIs, those p
140b0 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31  ostfixed with "1
140c0 36 22 20 72 65 74 75 72 6e 20 55 54 46 2d 31 36  6" return UTF-16
140d0 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 73 74 72 69  .** encoded stri
140e0 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66  ngs, the other f
140f0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
14100 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  UTF-8..**.** The
14110 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
14120 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
14130 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
14140 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
14150 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  .** SQLITE_ENABL
14160 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
14170 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  A preprocessor s
14180 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
14190 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
141a0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
141b0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
141c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
141d0 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
141e0 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
141f0 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
14200 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
14210 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
14220 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
14230 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
14240 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
14250 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
14260 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
14270 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
14280 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
14290 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
142a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
142b0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
142c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
142d0 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
142e0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
142f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
14300 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
14310 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
14320 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
14330 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
14340 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
14350 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
14360 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
14370 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
14380 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
14390 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
143a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
143b0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
143c0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
143d0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Result.**.** The
143e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
143f0 20 69 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   is a [sqlite3_s
14400 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53  tmt | compiled S
14410 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a  QL statement]. .
14420 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
14430 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54  ment is a SELECT
14440 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
14450 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
14460 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65   the .** returne
14470 64 20 72 65 73 75 6c 74 20 73 65 74 20 20 6f 66  d result set  of
14480 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20   that SELECT is 
14490 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
144a0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
144b0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
144c0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
144d0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
144e0 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
144f0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20  is returned. If 
14500 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
14510 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
14520 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
14530 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
14540 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
14550 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
14560 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
14570 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
14580 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
14590 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d. For example, 
145a0 69 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  in.** the databa
145b0 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
145c0 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
145d0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
145e0 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c  .** And the foll
145f0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
14600 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
14610 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
14620 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
14630 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   Then this routi
14640 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
14650 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
14660 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
14670 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f  ond.** result co
14680 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
14690 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
146a0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
146b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28  sult column.** (
146c0 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  i==0)..**.** SQL
146d0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
146e0 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
146f0 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75  .  So just becau
14700 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
14710 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
14720 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
14730 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
14740 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
14750 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
14760 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
14770 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
14780 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
14790 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
147a0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
147b0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
147c0 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a  t static.  Type.
147d0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
147e0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
147f0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
14800 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
14810 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
14820 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
14830 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
14840 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
14850 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
14860 6d 74 20 2a 2c 20 69 6e 74 20 69 29 3b 0a 63 6f  mt *, int i);.co
14870 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
14880 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
14890 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
148a0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20  *,int);../* .** 
148b0 43 41 50 49 33 52 45 46 3a 20 20 45 76 61 6c 75  CAPI3REF:  Evalu
148c0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
148d0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
148e0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d   an [sqlite3_stm
148f0 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  t | SQL statemen
14900 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
14910 61 72 65 64 20 77 69 74 68 20 61 20 63 61 6c 6c  ared with a call
14920 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b 73  .** to either [s
14930 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
14940 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
14950 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
14960 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a   or to one of.**
14970 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
14980 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
14990 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
149a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
149b0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  ()],.** then thi
149c0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  s function must 
149d0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
149e0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
149f0 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a 20  valuate the .** 
14a00 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
14a10 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
14a20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
14a30 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74 65  this sqlite3_ste
14a40 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
14a50 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
14a60 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
14a70 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
14a80 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
14a90 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
14aa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14ab0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
14ac0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
14ad0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
14ae0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
14af0 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
14b00 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
14b10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
14b20 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
14b30 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
14b40 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
14b50 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
14b60 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
14b70 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
14b80 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
14b90 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
14ba0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  pported..**.** I
14bb0 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69 6e 74  n the lagacy int
14bc0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
14bd0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
14be0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
14bf0 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49  BUSY], .** [SQLI
14c00 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
14c10 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
14c20 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
14c30 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57  TE_MISUSE]..** W
14c40 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
14c50 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
14c60 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45  he other [SQLITE
14c70 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
14c80 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  e].** or [SQLITE
14c90 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
14ca0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
14cb0 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  de] might be ret
14cc0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c  urned as.** well
14cd0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
14ce0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
14cf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
14d00 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
14d10 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
14d20 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
14d30 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
14d40 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65  its job.  If the
14d50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
14d60 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63  COMMIT.** or occ
14d70 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
14d80 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
14d90 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
14da0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
14db0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
14dc0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
14dd0 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61  s not a COMMIT a
14de0 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
14df0 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
14e00 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
14e10 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
14e20 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
14e30 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
14e40 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
14e50 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
14e60 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
14e70 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
14e80 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
14e90 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
14ea0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
14eb0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
14ec0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
14ed0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
14ee0 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
14ef0 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
14f00 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
14f10 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
14f20 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
14f30 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
14f40 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
14f50 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
14f60 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
14f70 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
14f80 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51  ta, then .** [SQ
14f90 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65 74  LITE_ROW] is ret
14fa0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
14fb0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
14fc0 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f  a is ready.** fo
14fd0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
14fe0 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  the caller. The 
14ff0 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
15000 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  cessed using.** 
15010 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
15020 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e  umn_int | column
15030 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
15040 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
15050 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
15060 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
15070 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
15080 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b  f data..** .** [
15090 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
150a0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
150b0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
150c0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
150d0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
150e0 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
150f0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
15100 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
15110 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
15120 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
15130 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
15140 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
15150 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
15160 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65  ..** With the le
15170 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
15180 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
15190 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d  error code (exam
151a0 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple:.** [SQLITE_
151b0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
151c0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
151d0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
151e0 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
151f0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
15200 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
15210 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
15220 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
15230 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
15240 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
15250 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
15260 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
15270 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
15280 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
15290 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
152a0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
152b0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
152c0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
152d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
152e0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
152f0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
15300 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
15310 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65 33  ed on a [sqlite3
15320 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
15330 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
15340 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
15350 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
15360 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
15370 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
15380 61 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69  at had .** previ
15390 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
153a0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
153b0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
153c0 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
153d0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
153e0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
153f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
15400 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
15410 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
15420 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
15430 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
15440 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
15450 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
15460 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20  :</b>.** In the 
15470 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
15480 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  , .** the sqlite
15490 33 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c 77  3_step() API alw
154a0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
154b0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
154c0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
154d0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
154e0 6e 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ny error other t
154f0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
15500 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45  ].** and [SQLITE
15510 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
15520 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  ust call [sqlite
15530 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
15540 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
15550 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
15560 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
15570 65 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53  e specific.** [S
15580 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65  QLITE_ERROR | re
15590 73 75 6c 74 20 63 6f 64 65 73 5d 20 74 68 61 74  sult codes] that
155a0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
155b0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
155c0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
155d0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
155e0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
155f0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
15600 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
15610 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
15620 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
15630 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
15640 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
15650 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
15660 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
15670 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
15680 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
15690 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
156a0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
156b0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
156c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
156d0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a  )], then the .**
156e0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
156f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
15700 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65  esult codes] are
15710 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
15720 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
15730 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
15740 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
15750 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
15760 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
15770 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
15780 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
15790 2a 2a 20 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a  ** CAPI3REF:.**.
157a0 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75  ** Return the nu
157b0 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
157c0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
157d0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
157e0 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  set..**.** After
157f0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
15800 74 65 33 5f 73 74 65 70 28 29 5d 20 74 68 61 74  te3_step()] that
15810 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
15820 5f 52 4f 57 5d 2c 20 74 68 69 73 20 72 6f 75 74  _ROW], this rout
15830 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  ine.** will retu
15840 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  rn the same valu
15850 65 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65  e as the [sqlite
15860 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
15870 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41  ] function..** A
15880 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
15890 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
158a0 65 64 20 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f  ed an [SQLITE_DO
158b0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  NE], [SQLITE_BUS
158c0 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c  Y], or.** a [SQL
158d0 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f  ITE_ERROR | erro
158e0 72 20 63 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f  r code], or befo
158f0 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
15900 28 29 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a  ()] has been .**
15910 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b   called on the [
15920 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
15930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
15940 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  t] for the first
15950 20 74 69 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72   time,.** this r
15960 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
15970 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ero..*/.int sqli
15980 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
15990 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
159a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
159b0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
159c0 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a  l Datatypes.**.*
159d0 2a 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  * Every value in
159e0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
159f0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
15a00 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
15a10 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
15a20 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
15a30 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
15a40 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
15a50 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
15a60 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
15a70 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
15a80 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
15a90 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ul>.**.** These 
15aa0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
15ab0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
15ac0 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
15ad0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
15ae0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
15af0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
15b00 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
15b10 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
15b20 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
15b30 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
15b40 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
15b50 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
15b60 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
15b70 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
15b80 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
15b90 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
15ba0 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  T not.** SQLITE_
15bb0 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
15bc0 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
15bd0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
15be0 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
15bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
15c00 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
15c10 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
15c20 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
15c30 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
15c40 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
15c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
15c60 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
15c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
15c80 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
15c90 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
15ca0 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  lts Values From 
15cb0 41 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68  A Query.**.** Th
15cc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
15cd0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
15ce0 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67 6c  about.** a singl
15cf0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
15d00 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72  current result r
15d10 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
15d20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65  In every.** case
15d30 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
15d40 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
15d50 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   to the .** [sql
15d60 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
15d70 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
15d80 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c  is being.** eval
15d90 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
15da0 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20  te3_stmt*] that 
15db0 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
15dc0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  m .** [sqlite3_p
15dd0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
15de0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
15df0 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20  nts) and.** the 
15e00 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15e10 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
15e20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
15e30 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
15e40 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72   .** should be r
15e50 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65  eturned.  The le
15e60 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  ft-most column o
15e70 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
15e80 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e 64 65 78  .** has an index
15e90 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20   of 0..**.** If 
15ea0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
15eb0 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
15ec0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
15ed0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
15ee0 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e  he.** the column
15ef0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
15f00 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
15f10 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
15f20 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69   .** These routi
15f30 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
15f40 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
15f50 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
15f60 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
15f70 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
15f80 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
15f90 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
15fa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
15fb0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
15fc0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73 20  finalize()] has 
15fd0 62 65 65 6e 20 63 61 6c 6c 20 73 75 62 73 65 71  been call subseq
15fe0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
15ff0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
16000 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
16010 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
16020 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
16030 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
16040 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
16050 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
16060 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
16070 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
16080 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
16090 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
160a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
160b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
160c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
160d0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
160e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
160f0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
16100 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
16110 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
16120 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
16130 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
16140 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
16150 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 20   are undefined. 
16160 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69   .**.** The sqli
16170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
16180 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
16190 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  s .** [SQLITE_IN
161a0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
161b0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
161c0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
161d0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
161e0 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
161f0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
16200 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
16210 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
16220 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
16230 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
16240 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
16250 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
16260 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
16270 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
16280 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
16290 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
162a0 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
162b0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
162c0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
162d0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
162e0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
162f0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
16300 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
16310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
16320 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
16330 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
16340 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
16350 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
16360 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
16370 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
16380 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
16390 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
163a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
163b0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
163c0 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
163d0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
163e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
163f0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
16400 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
16410 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
16420 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
16430 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
16440 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
16450 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
16460 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
16470 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
16480 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
16490 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
164a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
164b0 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  bytes..** If the
164c0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
164d0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
164e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
164f0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
16500 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
16510 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
16520 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
16530 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
16540 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
16550 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
16560 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
16570 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
16580 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
16590 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
165a0 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
165b0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
165c0 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72  tring.  For clar
165d0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
165e0 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
165f0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
16600 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
16610 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
16620 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
16630 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
16640 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
16650 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
16660 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
16670 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
16680 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
16690 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
166a0 36 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46  6 instead of UTF
166b0 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72  -8.  .** The zer
166c0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
166d0 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
166e0 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
166f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
16700 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
16710 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
16720 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
16730 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
16740 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
16750 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
16760 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
16770 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
16780 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
16790 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
167a0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
167b0 61 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65 20 63  ally to do the c
167c0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74  onversion.** aut
167d0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
167e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
167f0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
16800 76 65 72 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a  versions that.**
16810 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
16820 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
16830 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
16840 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
16850 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
16860 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
16870 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
16880 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
16890 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
168a0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
168b0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
168c0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
168d0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
168e0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
168f0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
16900 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
16910 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
16920 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
16930 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
16940 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
16950 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
16960 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
16970 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
16980 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
16990 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
169a0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
169b0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
169c0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
169d0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
169e0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
169f0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
16a00 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
16a10 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
16a20 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
16a30 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72 20 49  d> Same as for I
16a40 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
16a50 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
16a60 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
16a70 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
16a80 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
16a90 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
16aa0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
16ab0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
16ac0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
16ad0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
16ae0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
16af0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
16b00 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
16b10 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
16b20 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
16b30 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
16b40 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
16b50 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
16b60 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
16b70 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
16b80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
16b90 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
16ba0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
16bb0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
16bc0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
16bd0 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
16be0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
16bf0 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
16c00 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
16c10 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
16c20 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
16c30 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
16c40 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
16c50 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
16c60 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
16c70 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
16c80 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
16c90 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
16ca0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
16cb0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
16cc0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
16cd0 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
16ce0 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
16cf0 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
16d00 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
16d10 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
16d20 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
16d30 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
16d40 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e 74 20  * on equavalent 
16d50 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
16d60 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
16d70 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
16d80 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
16d90 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
16da0 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
16db0 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
16dc0 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
16dd0 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
16de0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
16df0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
16e00 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
16e10 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
16e20 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
16e30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
16e40 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
16e50 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
16e60 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
16e70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
16e80 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
16e90 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f  ted. .** Type co
16ea0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
16eb0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
16ec0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
16ed0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
16ee0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
16ef0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e   <ul>.** <li><p>
16f00 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
16f10 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
16f20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
16f30 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20 20  mn_text() .**   
16f40 20 20 20 20 20 20 20 6f 72 20 73 71 6c 69 74 65         or sqlite
16f50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
16f60 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
16f70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
16f80 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 20 20  might.**        
16f90 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
16fa0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
16fb0 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  .</p></li>.**.**
16fc0 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
16fd0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
16fe0 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
16ff0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
17000 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
17010 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
17020 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
17030 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
17040 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
17050 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
17060 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
17070 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  </p></li>.**.** 
17080 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69  <li><p>  The ini
17090 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
170a0 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
170b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
170c0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
170d0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
170e0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
170f0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
17100 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
17110 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  erted.**        
17120 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c    to UTF-8.</p><
17130 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
17140 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20  .** Conversions 
17150 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
17160 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
17170 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
17180 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
17190 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
171a0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
171b0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
171c0 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
171d0 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
171e0 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
171f0 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20  inter points to 
17200 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
17210 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
17220 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
17230 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
17240 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
17250 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
17260 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 20 69 73  t sometime it is
17270 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
17280 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
17290 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
172a0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
172b0 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ed.  .**.** The 
172c0 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
172d0 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
172e0 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
172f0 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
17300 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
17310 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
17320 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a  s:.**.**  <ul>.*
17330 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
17340 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
17350 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
17360 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
17370 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
17380 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
17390 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
173a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
173b0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
173c0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
173d0 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
173e0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
173f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
17400 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a  /li>.**  </ul>.*
17410 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
17420 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
17430 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
17440 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  umn_text(), sqli
17450 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
17460 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ),.** or sqlite3
17470 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
17480 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
17490 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
174a0 74 68 65 20 64 65 73 69 72 65 64 0a 2a 2a 20 66  the desired.** f
174b0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
174c0 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
174d0 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 73 71 6c  n_bytes() or sql
174e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
174f0 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64  s16() to.** find
17500 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
17510 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
17520 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c   mix call to sql
17530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
17540 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
17550 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
17560 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
17570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
17580 73 31 36 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e  s16().  And do n
17590 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20  ot.** mix calls 
175a0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
175b0 6e 5f 74 65 78 74 31 36 28 29 20 77 69 74 68 20  n_text16() with 
175c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
175d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
175e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
175f0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
17600 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
17610 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
17620 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
17630 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
17640 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
17650 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
17660 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
17670 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
17680 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
17690 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70  .  The memory sp
176a0 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
176b0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
176c0 62 6c 6f 62 73 20 69 73 20 66 72 65 65 64 20 61  blobs is freed a
176d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
176e0 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
176f0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
17700 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
17710 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
17720 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
17730 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
17740 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69  . into .** [sqli
17750 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
17760 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61  ** If a memory a
17770 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
17780 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
17790 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
177a0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
177b0 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
177c0 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
177d0 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
177e0 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
177f0 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
17800 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
17810 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
17820 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
17830 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
17840 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
17850 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
17860 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
17870 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
17880 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  ]..*/.const void
17890 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
178a0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
178b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
178c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
178d0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
178e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
178f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
17900 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
17910 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
17920 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
17930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
17940 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
17950 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
17960 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
17970 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
17980 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
17990 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
179a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
179b0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
179c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
179d0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
179e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
179f0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
17a00 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
17a10 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
17a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
17a30 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
17a40 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
17a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
17a60 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
17a70 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
17a80 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
17a90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
17aa0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
17ab0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
17ac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
17ad0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
17ae0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
17af0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
17b00 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
17b10 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
17b20 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a   to delete a .**
17b30 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
17b40 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74   compiled SQL st
17b50 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65  atement]. If the
17b60 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
17b70 2a 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65  * executed succe
17b80 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20  ssfully, or not 
17b90 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c  executed at all,
17ba0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20   then SQLITE_OK 
17bb0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
17bc0 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  If execution of 
17bd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61  the statement fa
17be0 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a  iled then an .**
17bf0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c   [SQLITE_ERROR |
17c00 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20   error code] or 
17c10 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
17c20 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72  AD | extended er
17c30 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20  ror code].** is 
17c40 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a  returned. .**.**
17c50 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61   This routine ca
17c60 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
17c70 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20  ny point during 
17c80 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
17c90 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
17ca0 5f 73 74 6d 74 20 7c 20 76 69 72 74 75 61 6c 20  _stmt | virtual 
17cb0 6d 61 63 68 69 6e 65 5d 2e 20 20 49 66 20 74 68  machine].  If th
17cc0 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  e virtual machin
17cd0 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f  e has not .** co
17ce0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
17cf0 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74  n when this rout
17d00 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  ine is called, t
17d10 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65  hat is like.** e
17d20 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65  ncountering an e
17d30 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72  rror or an inter
17d40 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c  rupt.  (See [sql
17d50 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
17d60 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65  ].) .** Incomple
17d70 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62  te updates may b
17d80 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e  e rolled back an
17d90 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63  d transactions c
17da0 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64  ancelled,  .** d
17db0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
17dc0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
17dd0 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  nd the .** [SQLI
17de0 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c  TE_ERROR | resul
17df0 74 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64  t code] returned
17e00 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45   will be [SQLITE
17e10 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20  _ABORT]..*/.int 
17e20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
17e30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
17e40 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
17e50 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
17e60 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
17e70 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
17e80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
17e90 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
17ea0 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
17eb0 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  a .** [sqlite3_s
17ec0 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53  tmt | compiled S
17ed0 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  QL statement] ob
17ee0 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f  ject..** back to
17ef0 20 69 74 27 73 20 69 6e 69 74 69 61 6c 20 73 74   it's initial st
17f00 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
17f10 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
17f20 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
17f30 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
17f40 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
17f50 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
17f60 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
17f70 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
17f80 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
17f90 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
17fa0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
17fb0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
17fc0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
17fd0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
17fe0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
17ff0 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
18000 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
18010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
18020 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
18030 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
18040 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
18050 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  g two functions 
18060 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
18070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
18080 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f   aggregates.** o
18090 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
180a0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 65 78  e behavior of ex
180b0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
180c0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
180d0 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69 66 66  es.  The.** diff
180e0 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77  erence only betw
180f0 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73 20 74  een the two is t
18100 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70  hat the second p
18110 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a  arameter, the.**
18120 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63   name of the (sc
18130 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f  alar) function o
18140 72 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20  r aggregate, is 
18150 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
18160 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
18170 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
18180 29 20 61 6e 64 20 55 54 46 2d 31 36 20 66 6f 72  ) and UTF-16 for
18190 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
181a0 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  function16()..**
181b0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
181c0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 5b 73  gument is the [s
181d0 71 6c 69 74 65 33 20 7c 20 64 61 74 61 62 61 73  qlite3 | databas
181e0 65 20 68 61 6e 64 6c 65 5d 20 74 68 61 74 20 68  e handle] that h
181f0 6f 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51 4c 20  olds the.** SQL 
18200 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
18210 65 67 61 74 65 20 69 73 20 74 6f 20 62 65 20 61  egate is to be a
18220 64 64 65 64 20 6f 72 20 72 65 64 65 66 69 6e 65  dded or redefine
18230 64 2e 20 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a  d. If a single.*
18240 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d  * program uses m
18250 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
18260 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 6e 74  abase handle int
18270 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51  ernally, then SQ
18280 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6f  L.** functions o
18290 72 20 61 67 67 72 65 67 61 74 65 73 20 6d 75 73  r aggregates mus
182a0 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76  t be added indiv
182b0 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20  idually to each 
182c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64  database.** hand
182d0 6c 65 20 77 69 74 68 20 77 68 69 63 68 20 74 68  le with which th
182e0 65 79 20 77 69 6c 6c 20 62 65 20 75 73 65 64 2e  ey will be used.
182f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
18300 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
18310 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
18320 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
18330 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20  e created.** or 
18340 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  redefined..** Th
18350 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
18360 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
18370 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78  to 255 bytes, ex
18380 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 0a  clusive of the .
18390 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ** zero-terminat
183a0 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  or.  Note that t
183b0 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c  he name length l
183c0 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73  imit is in bytes
183d0 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74  , not.** charact
183e0 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  ers.  Any attemp
183f0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
18400 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
18410 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
18420 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 53  l result in an S
18430 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72 6f  QLITE_ERROR erro
18440 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  r..**.** The thi
18450 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
18460 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
18470 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
18480 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
18490 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
184a0 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72  kes. If this par
184b0 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
184c0 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  ve, then the SQL
184d0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
184e0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
184f0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
18500 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
18510 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
18520 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
18530 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
18540 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
18550 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
18560 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
18570 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
18580 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
18590 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
185a0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
185b0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
185c0 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
185d0 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
185e0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
185f0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
18600 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
18610 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
18620 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
18630 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
18640 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73   another.  It is
18650 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69   allowed to.** i
18660 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
18670 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
18680 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
18690 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
186a0 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
186b0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
186c0 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
186d0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
186e0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
186f0 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  * When multiple 
18700 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
18710 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
18720 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
18730 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
18740 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
18750 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
18760 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
18770 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
18780 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
18790 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
187a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
187b0 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
187c0 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74 20  re what.** text 
187d0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
187e0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
187f0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
18800 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  d be.** [SQLITE_
18810 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ANY]..**.** The 
18820 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
18830 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
18840 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
18850 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
18860 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
18870 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
18880 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
18890 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
188a0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a  3_user_data()]..
188b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74  **.** The sevent
188c0 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69  h, eighth and ni
188d0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  nth parameters, 
188e0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
188f0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
18900 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
18910 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
18920 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
18930 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
18940 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
18950 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66  . A scalar SQL f
18960 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
18970 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
18980 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 75  on of.** the xFu
18990 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  nc callback only
189a0 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  , NULL pointers 
189b0 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
189c0 20 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a 2a   as the xStep.**
189d0 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72 61   and xFinal para
189e0 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65  meters. An aggre
189f0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
18a00 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
18a10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
18a20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  of xStep and xFi
18a30 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f  nal and NULL sho
18a40 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f  uld be passed fo
18a50 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65  r xFunc. To dele
18a60 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69 6e  te an.** existin
18a70 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  g SQL function o
18a80 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
18a90 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74  s NULL for all t
18aa0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
18ab0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
18ac0 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64   It is permitted
18ad0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
18ae0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
18af0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
18b00 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
18b10 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
18b20 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
18b30 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
18b40 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
18b50 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
18b60 20 70 65 72 66 65 72 72 65 64 20 74 65 78 74 20   perferred text 
18b70 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69  encodings.  SQLi
18b80 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
18b90 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
18ba0 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  n most closely m
18bb0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
18bc0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
18bd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
18be0 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  sed..*/.int sqli
18bf0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
18c00 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
18c10 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
18c20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
18c30 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
18c40 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
18c50 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  d*,.  void (*xFu
18c60 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
18c70 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
18c80 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
18c90 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
18ca0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
18cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
18cc0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
18cd0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
18ce0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
18cf0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
18d00 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
18d10 2a 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  *,.  const void 
18d20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
18d30 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
18d40 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
18d50 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  id*,.  void (*xF
18d60 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
18d70 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
18d80 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
18d90 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
18da0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
18db0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
18dc0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
18dd0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
18de0 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ext*).);../*.** 
18df0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
18e00 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
18e10 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
18e20 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
18e30 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
18e40 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
18e50 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
18e60 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
18e70 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
18e80 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
18e90 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
18ea0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
18eb0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
18ec0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
18ed0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
18ee0 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
18ef0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
18f00 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
18f10 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
18f20 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
18f30 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
18f40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
18f50 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
18f60 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
18f70 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
18f80 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
18f90 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
18fa0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
18fb0 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75  REF: Obsolete Fu
18fc0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
18fd0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
18fe0 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65  e all now obsole
18ff0 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  te.  In order to
19000 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
19010 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
19020 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
19030 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75  code, we continu
19040 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20  e to support.** 
19050 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
19060 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64    However, new d
19070 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65  evelopment proje
19080 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  cts should avoid
19090 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
190a0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
190b0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
190c0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
190d0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
190e0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
190f0 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
19100 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74   tell you want t
19110 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73  hey do..*/.int s
19120 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
19130 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
19140 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71  ontext*);.int sq
19150 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
19160 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e  lite3_stmt*);.in
19170 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
19180 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
19190 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
191a0 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73  e3_stmt*);.int s
191b0 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
191c0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69  cover(void);.voi
191d0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
191e0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
191f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19200 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
19210 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
19220 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
19230 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
19240 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
19250 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
19260 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
19270 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
19280 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
19290 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
192a0 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
192b0 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
192c0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
192d0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
192e0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
192f0 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
19300 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
19310 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
19320 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
19330 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
19340 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
19350 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
19360 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
19370 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
19380 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
19390 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
193a0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
193b0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
193c0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
193d0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
193e0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
193f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
19400 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
19410 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
19420 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
19430 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
19440 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
19450 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
19460 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
19470 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
19480 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
19490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
194a0 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
194b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
194c0 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
194d0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a  corresponding .*
194e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
194f0 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  n_blob | sqlite3
19500 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e  _column_* routin
19510 65 73 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  es] except that 
19520 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
19530 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
19540 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
19550 5d 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  ] pointer instea
19560 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  d.** of an [sqli
19570 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
19580 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
19590 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
195a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
195b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
195c0 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
195d0 61 63 74 73 20 61 20 55 54 46 31 36 20 73 74 72  acts a UTF16 str
195e0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
195f0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
19600 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
19610 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ine.  The.** sql
19620 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
19630 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
19640 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
19650 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
19660 20 65 78 74 72 61 63 74 20 55 54 46 31 36 20 73   extract UTF16 s
19670 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
19680 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
19690 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
196a0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
196b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
196c0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
196d0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
196e0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
196f0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
19700 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
19710 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
19720 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
19730 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
19740 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
19750 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
19760 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
19770 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
19780 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
19790 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
197a0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 72 64 65  rmation (in orde
197b0 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68  r.** words if th
197c0 65 20 76 61 6c 75 65 20 69 73 20 6f 72 69 67 69  e value is origi
197d0 6e 61 6c 20 61 20 73 74 72 69 6e 67 20 74 68 61  nal a string tha
197e0 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
197f0 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 69  umber).** then i
19800 74 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65  t is done.  Othe
19810 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
19820 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ion occurs.  The
19830 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54   .** [SQLITE_INT
19840 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
19850 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
19860 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  n is returned..*
19870 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
19880 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
19890 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
198a0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
198b0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72 65 74  r that.** is ret
198c0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
198d0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
198e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
198f0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
19900 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
19910 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
19920 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
19930 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
19940 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
19950 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
19960 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
19970 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
19980 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
19990 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
199a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
199b0 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73  )].  .**.** Thes
199c0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
199d0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
199e0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
199f0 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
19a00 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
19a10 69 65 64 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ied the sqlite3_
19a20 76 61 6c 75 65 2a 20 70 61 72 61 6d 65 74 65 72  value* parameter
19a30 73 2e 0a 2a 2a 20 4f 72 2c 20 69 66 20 74 68 65  s..** Or, if the
19a40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20   sqlite3_value* 
19a50 61 72 67 75 6d 65 6e 74 20 63 6f 6d 65 73 20 66  argument comes f
19a60 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
19a70 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
19a80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2c 20 74  .** interface, t
19a90 68 65 6e 20 74 68 65 73 65 20 72 6f 75 74 69 6e  hen these routin
19aa0 65 73 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  es should be cal
19ab0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
19ac0 65 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 74  e thread.** that
19ad0 20 72 61 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6f   ran [sqlite3_co
19ae0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  lumn_value()]..*
19af0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
19b00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
19b10 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
19b20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
19b30 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
19b40 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
19b50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
19b60 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
19b70 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
19b80 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
19b90 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
19ba0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
19bb0 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
19bc0 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
19bd0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
19be0 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
19bf0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
19c00 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
19c10 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
19c20 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
19c30 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
19c40 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
19c50 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
19c60 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
19c70 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
19c80 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
19c90 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
19ca0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
19cb0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
19cc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
19cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
19ce0 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
19cf0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
19d00 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
19d10 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
19d20 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
19d30 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
19d40 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
19d50 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
19d60 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
19d70 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65  ion of aggregate
19d80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
19d90 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
19da0 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61  to allocate.** a
19db0 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73   structure for s
19dc0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
19dd0 74 65 2e 20 20 54 68 65 20 66 69 72 73 74 20 74  te.  The first t
19de0 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
19df0 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  .** is called fo
19e00 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
19e10 67 67 72 65 67 61 74 65 2c 20 61 20 6e 65 77 20  ggregate, a new 
19e20 73 74 72 75 63 74 75 72 65 20 6f 66 20 73 69 7a  structure of siz
19e30 65 20 6e 42 79 74 65 73 0a 2a 2a 20 69 73 20 61  e nBytes.** is a
19e40 6c 6c 6f 63 61 74 65 64 2c 20 7a 65 72 6f 65 64  llocated, zeroed
19e50 2c 20 61 6e 64 20 72 65 74 75 72 6e 65 64 2e 20  , and returned. 
19e60 20 4f 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   On subsequent c
19e70 61 6c 6c 73 20 28 66 6f 72 20 74 68 65 0a 2a 2a  alls (for the.**
19e80 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
19e90 69 6e 73 74 61 6e 63 65 29 20 74 68 65 20 73 61  instance) the sa
19ea0 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
19eb0 75 72 6e 65 64 2e 20 20 54 68 65 20 69 6d 70 6c  urned.  The impl
19ec0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66  ementation.** of
19ed0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63   the aggregate c
19ee0 61 6e 20 75 73 65 20 74 68 65 20 72 65 74 75 72  an use the retur
19ef0 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63  ned buffer to ac
19f00 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a  cumulate data..*
19f10 2a 0a 2a 2a 20 54 68 65 20 62 75 66 66 65 72 20  *.** The buffer 
19f20 61 6c 6c 6f 63 61 74 65 64 20 69 73 20 66 72 65  allocated is fre
19f30 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
19f40 20 62 79 20 53 51 4c 69 74 65 20 77 68 61 6e 20   by SQLite whan 
19f50 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
19f60 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
19f70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
19f80 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  t parameter shou
19f90 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  ld be a copy of 
19fa0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
19fb0 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
19fc0 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
19fd0 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
19fe0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
19ff0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1a000 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
1a010 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
1a020 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
1a030 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
1a040 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
1a050 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
1a060 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
1a070 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
1a080 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
1a090 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
1a0a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
1a0b0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
1a0c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1a0d0 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
1a0e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a0f0 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
1a100 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1a110 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
1a120 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
1a130 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1a140 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
1a150 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
1a160 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
1a170 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74  utines.** used t
1a180 6f 20 72 65 67 69 73 74 65 72 20 75 73 65 72 20  o register user 
1a190 66 75 6e 63 74 69 6f 6e 73 20 69 73 20 61 76 61  functions is ava
1a1a0 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a 20 74 68 65  ilable to.** the
1a1b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1a1c0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
1a1d0 75 73 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  using this call.
1a1e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1a1f0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
1a200 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
1a210 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
1a220 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
1a230 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
1a240 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1a250 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
1a260 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
1a270 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a280 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
1a290 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
1a2a0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
1a2b0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
1a2c0 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
1a2d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
1a2e0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
1a2f0 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 72 67  ta-data with arg
1a300 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
1a310 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
1a320 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
1a330 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
1a340 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
1a350 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
1a360 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
1a370 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
1a380 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
1a390 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
1a3a0 20 6d 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62   meta-data may b
1a3b0 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
1a3c0 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
1a3d0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
1a3e0 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
1a3f0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
1a400 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
1a410 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
1a420 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
1a430 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
1a440 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
1a450 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61   as.** meta-data
1a460 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1a470 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
1a480 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
1a490 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
1a4a0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
1a4b0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
1a4c0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
1a4d0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
1a4e0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
1a4f0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
1a500 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
1a510 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
1a520 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
1a530 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
1a540 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
1a550 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
1a560 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
1a570 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
1a580 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
1a590 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1a5a0 20 74 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74   to the meta-dat
1a5b0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
1a5c0 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
1a5d0 75 6d 65 6e 74 20 76 61 6c 75 65 20 74 6f 20 74  ument value to t
1a5e0 68 65 20 63 75 72 72 65 6e 74 20 53 51 4c 20 66  he current SQL f
1a5f0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 2c  unction.** call,
1a600 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1a610 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a620 2e 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74  . If no meta-dat
1a630 61 20 68 61 73 20 62 65 65 6e 20 73 65 74 20 66  a has been set f
1a640 6f 72 0a 2a 2a 20 74 68 61 74 20 76 61 6c 75 65  or.** that value
1a650 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
1a660 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
1a670 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1a680 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
1a690 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 61 73  () is used to as
1a6a0 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74  sociate meta-dat
1a6b0 61 20 77 69 74 68 20 61 6e 20 53 51 4c 0a 2a 2a  a with an SQL.**
1a6c0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
1a6d0 6e 74 2e 20 54 68 65 20 74 68 69 72 64 20 70 61  nt. The third pa
1a6e0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
1a6f0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
1a700 2d 64 61 74 61 0a 2a 2a 20 74 6f 20 62 65 20 61  -data.** to be a
1a710 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1a720 68 65 20 4e 74 68 20 75 73 65 72 20 66 75 6e 63  he Nth user func
1a730 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 20 76 61  tion argument va
1a740 6c 75 65 2e 20 54 68 65 20 66 6f 75 72 74 68 0a  lue. The fourth.
1a750 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 70 65  ** parameter spe
1a760 63 69 66 69 65 73 20 61 20 64 65 73 74 72 75 63  cifies a destruc
1a770 74 6f 72 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tor that will be
1a780 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 6d   called on the m
1a790 65 74 61 2d 0a 2a 2a 20 64 61 74 61 20 70 6f 69  eta-.** data poi
1a7a0 6e 74 65 72 20 74 6f 20 72 65 6c 65 61 73 65 20  nter to release 
1a7b0 69 74 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  it when it is no
1a7c0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
1a7d0 2e 20 49 66 20 74 68 65 20 0a 2a 2a 20 64 65 73  . If the .** des
1a7e0 74 72 75 63 74 6f 72 20 69 73 20 4e 55 4c 4c 2c  tructor is NULL,
1a7f0 20 69 74 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b   it is not invok
1a800 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61  ed..**.** In pra
1a810 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61  ctice, meta-data
1a820 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
1a830 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
1a840 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
1a850 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
1a860 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
1a870 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
1a880 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
1a890 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53  .** values and S
1a8a0 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a  QL variables..**
1a8b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1a8c0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
1a8d0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
1a8e0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
1a8f0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
1a900 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
1a910 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1a920 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
1a930 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
1a940 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
1a950 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
1a960 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1a970 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  int, void*, void
1a980 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
1a990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a9a0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
1a9b0 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
1a9c0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
1a9d0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
1a9e0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 66 6f 72  pecial value for
1a9f0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
1aa00 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
1aa10 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
1aa20 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
1aa30 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
1aa40 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
1aa50 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73  ()].  If the des
1aa60 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
1aa70 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
1aa80 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
1aa90 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
1aaa0 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
1aab0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
1aac0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
1aad0 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
1aae0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
1aaf0 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45    The .** SQLITE
1ab00 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
1ab10 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
1ab20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
1ab30 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
1ab40 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
1ab50 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
1ab60 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
1ab70 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
1ab80 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
1ab90 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
1aba0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
1abb0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
1abc0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
1abd0 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
1abe0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
1abf0 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
1ac00 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
1ac10 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
1ac20 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
1ac30 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
1ac40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1ac50 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
1ac60 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
1ac70 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
1ac80 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1ac90 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
1aca0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
1acb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1acc0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
1acd0 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
1ace0 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
1acf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1ad00 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
1ad10 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
1ad20 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
1ad30 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
1ad40 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
1ad50 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
1ad60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
1ad70 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
1ad80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
1ad90 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
1ada0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
1adb0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1adc0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
1add0 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
1ade0 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a 20 5b 73   like the .** [s
1adf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1ae00 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
1ae10 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  *] family of fun
1ae20 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a 2a 20 74  ctions used.** t
1ae30 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
1ae40 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
1ae50 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
1ae60 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
1ae70 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  r to the.** [sql
1ae80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1ae90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
1aea0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
1aeb0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
1aec0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1aed0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1aee0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
1aef0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
1af00 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
1af10 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
1af20 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
1af30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
1af40 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
1af50 6e 2e 20 20 54 68 65 0a 2a 2a 20 70 61 72 61 6d  n.  The.** param
1af60 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1af70 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
1af80 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
1af90 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 69 73  _error16().** is
1afa0 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
1afb0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
1afc0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1afd0 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
1afe0 20 63 61 75 73 65 20 74 68 65 20 66 75 6e 63 74   cause the funct
1aff0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
1b000 6f 6e 0a 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61  on.** to throw a
1b010 6e 64 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  nd error indicat
1b020 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
1b030 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20  g or BLOB is to 
1b040 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70 72 65  long.** to repre
1b050 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  sent..**.** Thes
1b060 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
1b070 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  be called from w
1b080 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
1b090 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
1b0a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  SQL function ass
1b0b0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1b0c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
1b0d0 74 5d 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 76  t] pointer..*/.v
1b0e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1b0f0 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
1b100 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
1b110 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
1b120 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
1b130 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1b140 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
1b150 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
1b160 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1b170 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
1b180 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
1b190 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
1b1a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1b1b0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
1b1c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1b1d0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1b1e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1b1f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
1b200 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
1b210 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
1b220 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
1b230 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
1b240 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
1b250 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
1b260 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
1b270 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
1b280 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
1b290 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
1b2a0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
1b2b0 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
1b2c0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
1b2d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
1b2e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1b2f0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
1b300 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
1b310 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
1b320 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1b330 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
1b340 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
1b350 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
1b360 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
1b370 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1b380 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
1b390 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
1b3a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
1b3b0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
1b3c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1b3d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1b3e0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
1b3f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1b400 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1b410 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
1b420 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1b430 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
1b440 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
1b450 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
1b460 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1b470 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
1b480 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
1b490 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
1b4a0 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
1b4b0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
1b4c0 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ences.**.** Thes
1b4d0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
1b4e0 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20  used to add new 
1b4f0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1b500 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73  ces to the.** [s
1b510 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20  qlite3*] handle 
1b520 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
1b530 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1b540 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65   .**.** The name
1b550 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c   of the new coll
1b560 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
1b570 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61  s specified as a
1b580 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
1b590 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
1b5a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
1b5b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
1b5c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
1b5d0 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
1b5e0 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c  6 string for sql
1b5f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
1b600 61 74 69 6f 6e 31 36 28 29 2e 20 20 49 6e 20 61  ation16().  In a
1b610 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
1b620 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
1b630 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
1b640 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
1b650 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
1b660 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
1b670 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
1b680 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54  tants [SQLITE_UT
1b690 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  F8],.** [SQLITE_
1b6a0 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c  UTF16LE] or [SQL
1b6b0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e  ITE_UTF16BE], in
1b6c0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68  dicating that th
1b6d0 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a  e user-supplied.
1b6e0 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  ** routine expec
1b6f0 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20  ts to be passed 
1b700 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
1b710 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  ngs encoded usin
1b720 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d  g UTF-8,.** UTF-
1b730 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
1b740 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65   or UTF-16 big-e
1b750 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
1b760 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e  ly..**.** A poin
1b770 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20  ter to the user 
1b780 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65  supplied routine
1b790 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
1b7a0 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20  as the fifth.** 
1b7b0 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
1b7c0 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73  is NULL, this is
1b7d0 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c   the same as del
1b7e0 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74  eting the collat
1b7f0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
1b800 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20  (so that SQLite 
1b810 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61  cannot call it a
1b820 6e 79 6d 6f 72 65 29 2e 20 45 61 63 68 20 74 69  nymore). Each ti
1b830 6d 65 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 73  me the user.** s
1b840 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
1b850 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
1b860 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
1b870 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61   of the void* pa
1b880 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 66  ssed as.** the f
1b890 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
1b8a0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
1b8b0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a  _collation() or.
1b8c0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
1b8d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20  e_collation16() 
1b8e0 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
1b8f0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
1b900 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
1b910 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 75 73 65  ments to the use
1b920 72 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  r-supplied routi
1b930 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
1b940 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
1b950 65 73 65 6e 74 65 64 20 62 79 20 61 20 5b 6c 65  esented by a [le
1b960 6e 67 74 68 2c 20 64 61 74 61 5d 20 70 61 69 72  ngth, data] pair
1b970 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
1b980 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
1b990 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
1b9a0 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
1b9b0 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
1b9c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
1b9d0 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
1b9e0 72 65 64 2e 20 54 68 65 20 75 73 65 72 20 72 6f  red. The user ro
1b9f0 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74  utine should ret
1ba00 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65  urn negative, ze
1ba10 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69  ro or positive i
1ba20 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 73  f.** the first s
1ba30 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
1ba40 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  an, equal to, or
1ba50 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
1ba60 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69  e second.** stri
1ba70 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47  ng. i.e. (STRING
1ba80 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a  1 - STRING2)..**
1ba90 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1baa0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1bab0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
1bac0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1bad0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65  collation().** e
1bae0 78 63 61 70 74 20 74 68 61 74 20 69 74 20 74 61  xcapt that it ta
1baf0 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67  kes an extra arg
1bb00 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
1bb10 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a   destructor for.
1bb20 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ** the collation
1bb30 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
1bb40 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
1bb50 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
1bb60 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
1bb70 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
1bb80 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
1bb90 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
1bba0 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
1bbb0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
1bbc0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
1bbd0 29 2e 20 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61  ).  Collations a
1bbe0 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65  re destroyed whe
1bbf0 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 6f 76  n.** they are ov
1bc00 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
1bc10 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  r calls to the c
1bc20 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
1bc30 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f  n functions.** o
1bc40 72 20 77 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  r when the [sqli
1bc50 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68  te3*] database h
1bc60 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20  andle is closed 
1bc70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
1bc80 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  lose()]..**.** T
1bc90 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
1bca0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
1bcb0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78   interface is ex
1bcc0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a  perimental and.*
1bcd0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1bce0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65  nge in future re
1bcf0 6c 65 61 73 65 73 2e 20 20 54 68 65 20 6f 74 68  leases.  The oth
1bd00 65 72 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  er collation cre
1bd10 61 74 69 6f 6e 0a 2a 2a 20 66 75 6e 63 74 69 6f  ation.** functio
1bd20 6e 73 20 61 72 65 20 73 74 61 62 6c 65 2e 0a 2a  ns are stable..*
1bd30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
1bd40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a  eate_collation(.
1bd50 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
1bd60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
1bd70 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
1bd80 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
1bd90 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
1bda0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
1bdb0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
1bdc0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
1bdd0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1bde0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
1bdf0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
1be00 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
1be10 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
1be20 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
1be30 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
1be40 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
1be50 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
1be60 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
1be70 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73  (void*).);.int s
1be80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1be90 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  llation16(.  sql
1bea0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
1beb0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
1bec0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
1bed0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
1bee0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
1bef0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
1bf00 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
1bf10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bf20 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
1bf30 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
1bf40 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61  *.** To avoid ha
1bf50 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
1bf60 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
1bf70 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
1bf80 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
1bf90 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
1bfa0 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
1bfb0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
1bfc0 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
1bfd0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e  .** database han
1bfe0 64 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64  dle to be called
1bff0 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
1c000 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
1c010 20 73 65 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20   sequence is.** 
1c020 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1c030 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
1c040 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
1c050 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1c060 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
1c070 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
1c080 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
1c090 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
1c0a0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
1c0b0 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
1c0c0 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
1c0d0 20 55 54 46 2d 38 2e 20 49 66 20 73 71 6c 69 74   UTF-8. If sqlit
1c0e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1c0f0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
1c100 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72   the names.** ar
1c110 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
1c120 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
1c130 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1c140 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65   A call to eithe
1c150 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
1c160 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73 74  places any exist
1c170 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ing callback..**
1c180 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1c190 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1c1a0 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
1c1b0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
1c1c0 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
1c1d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1c1e0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
1c1f0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
1c200 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
1c210 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
1c220 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  . The second arg
1c230 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
1c240 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e  abase.** handle.
1c250 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
1c260 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
1c270 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
1c280 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
1c290 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  r.** [SQLITE_UTF
1c2a0 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
1c2b0 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
1c2c0 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
1c2d0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
1c2e0 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
1c2f0 72 65 71 75 69 72 65 64 2e 20 54 68 65 20 66 6f  required. The fo
1c300 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1c310 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1c320 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
1c330 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1c340 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
1c350 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
1c360 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
1c370 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
1c380 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
1c390 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1c3a0 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
1c3b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1c3c0 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
1c3d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1c3e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
1c3f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1c400 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
1c410 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
1c420 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
1c430 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
1c440 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
1c450 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
1c460 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
1c470 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
1c480 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
1c490 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
1c4a0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
1c4b0 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
1c4c0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
1c4d0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
1c4e0 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
1c4f0 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
1c500 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
1c510 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
1c520 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
1c530 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
1c540 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
1c550 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
1c560 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
1c570 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
1c580 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
1c590 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
1c5a0 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
1c5b0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1c5c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1c5d0 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
1c5e0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
1c5f0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
1c600 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
1c610 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
1c620 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
1c630 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
1c640 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
1c650 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
1c660 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
1c670 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
1c680 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
1c690 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
1c6a0 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
1c6b0 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
1c6c0 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
1c6d0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
1c6e0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
1c6f0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
1c700 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
1c710 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
1c720 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1c730 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
1c740 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1c750 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1c760 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
1c770 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
1c780 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
1c790 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
1c7a0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
1c7b0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53 75 73  * CAPI3REF:  Sus
1c7c0 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
1c7d0 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a  or A Short Time.
1c7e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
1c7f0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
1c800 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
1c810 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
1c820 6f 6e 0a 2a 2a 20 61 20 6e 75 6d 62 65 72 20 6f  on.** a number o
1c830 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
1c840 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
1c850 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1c860 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
1c870 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
1c880 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
1c890 72 65 71 75 65 73 74 73 20 77 69 74 68 20 0a 2a  requests with .*
1c8a0 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
1c8b0 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
1c8c0 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
1c8d0 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
1c8e0 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65  to .** the neare
1c8f0 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
1c900 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
1c910 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
1c920 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75  ctually .** requ
1c930 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
1c940 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1c950 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1c960 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
1c970 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
1c980 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
1c990 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
1c9a0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
1c9b0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1c9c0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e  s] object..*/.in
1c9d0 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  t sqlite3_sleep(
1c9e0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
1c9f0 49 33 52 45 46 3a 20 20 4e 61 6d 65 20 4f 66 20  I3REF:  Name Of 
1ca00 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
1ca10 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
1ca20 65 73 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73  es.**.** If this
1ca30 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
1ca40 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
1ca50 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
1ca60 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
1ca70 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
1ca80 61 2e 6b 61 2e 20 64 69 72 65 63 74 6f 72 79 29  a.ka. directory)
1ca90 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
1caa0 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
1cab0 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
1cac0 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69  will be placed i
1cad0 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79  n that directory
1cae0 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 69 61  .  If this varia
1caf0 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70  ble.** is NULL p
1cb00 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
1cb10 69 74 65 20 64 6f 65 73 20 61 20 73 65 61 72 63  ite does a searc
1cb20 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
1cb30 69 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a  iate temporary.*
1cb40 2a 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  * file directory
1cb50 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
1cb60 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79  t safe to modify
1cb70 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f   this variable o
1cb80 6e 63 65 20 61 20 64 61 74 61 62 61 73 65 20 63  nce a database c
1cb90 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68 61 73  onnection.** has
1cba0 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49   been opened.  I
1cbb0 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
1cbc0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
1cbd0 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
1cbe0 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
1cbf0 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
1cc00 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
1cc10 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
1cc20 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
1cc30 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64  ve been call and
1cc40 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
1cc50 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f  d thereafter..*/
1cc60 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
1cc70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
1cc80 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
1cc90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 54  .** CAPI3REF:  T
1cca0 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1ccb0 65 20 44 61 74 61 62 61 73 65 20 49 73 20 49 6e  e Database Is In
1ccc0 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
1ccd0 65 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20  e.**.** Test to 
1cce0 73 65 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  see whether or n
1ccf0 6f 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ot the database 
1cd00 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e  connection is in
1cd10 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d   autocommit.** m
1cd20 6f 64 65 2e 20 20 52 65 74 75 72 6e 20 54 52 55  ode.  Return TRU
1cd30 45 20 69 66 20 69 74 20 69 73 20 61 6e 64 20 46  E if it is and F
1cd40 41 4c 53 45 20 69 66 20 6e 6f 74 2e 20 20 41 75  ALSE if not.  Au
1cd50 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
1cd60 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c   on.** by defaul
1cd70 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69  t.  Autocommit i
1cd80 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
1cd90 42 45 47 49 4e 20 73 74 61 74 65 6d 65 6e 74 20  BEGIN statement 
1cda0 61 6e 64 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a  and reenabled.**
1cdb0 20 62 79 20 74 68 65 20 6e 65 78 74 20 43 4f 4d   by the next COM
1cdc0 4d 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e  MIT or ROLLBACK.
1cdd0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
1cde0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
1cdf0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
1ce00 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
1ce10 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
1ce20 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
1ce30 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
1ce40 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
1ce50 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
1ce60 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
1ce70 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
1ce80 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
1ce90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1cea0 52 45 46 3a 20 20 46 69 6e 64 20 54 68 65 20 44  REF:  Find The D
1ceb0 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 41  atabase Handle A
1cec0 73 73 6f 63 69 61 74 65 64 20 57 69 74 68 20 41  ssociated With A
1ced0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
1cee0 65 6e 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  ent.**.** Return
1cef0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20   the [sqlite3*] 
1cf00 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
1cf10 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b 73  to which a.** [s
1cf20 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72  qlite3_stmt | pr
1cf30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1cf40 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68  ] belongs..** Th
1cf50 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 64  is is the same d
1cf60 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
1cf70 68 61 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66  hat was.** the f
1cf80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1cf90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
1cfa0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
1cfb0 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74  ts variants.** t
1cfc0 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 20  hat was used to 
1cfd0 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
1cfe0 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
1cff0 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69  t place..*/.sqli
1d000 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
1d010 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
1d020 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  tmt*);.../*.** C
1d030 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
1d040 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
1d050 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
1d060 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  cks.**.** These 
1d070 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 67 69  routines.** regi
1d080 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1d090 6e 63 74 69 6f 6e 73 20 74 6f 20 62 65 20 69 6e  nctions to be in
1d0a0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
1d0b0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
1d0c0 69 73 20 63 6f 6d 6d 69 74 74 65 64 20 6f 72 20  is committed or 
1d0d0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20 54 68  rolled back.  Th
1d0e0 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
1d0f0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
1d100 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  h.** to the call
1d110 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20 63 61  back.  If the ca
1d120 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
1d130 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
1d140 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e   .** returns non
1d150 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
1d160 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
1d170 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
1d180 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ack..**.** If an
1d190 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
1d1a0 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
1d1b0 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
1d1c0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
1d1d0 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  rned..** Otherwi
1d1e0 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
1d1f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  ned..**.** Regis
1d200 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
1d210 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
1d220 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
1d230 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
1d240 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
1d250 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
1d260 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
1d270 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20  been .** rolled 
1d280 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69  back if an expli
1d290 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73  cit "ROLLBACK" s
1d2a0 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63  tatement is exec
1d2b0 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65  uted, or.** an e
1d2c0 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69  rror or constrai
1d2d0 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70  nt causes an imp
1d2e0 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74  licit rollback t
1d2f0 6f 20 6f 63 63 75 72 2e 20 54 68 65 20 0a 2a 2a  o occur. The .**
1d300 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
1d310 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
1d320 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
1d330 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
1d340 64 0a 2a 2a 20 62 61 63 6b 20 62 65 63 61 75 73  d.** back becaus
1d350 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1d360 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1d370 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
1d380 20 61 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61   are experimenta
1d390 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64  l interfaces and
1d3a0 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20   are subject to 
1d3b0 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20  change..*/.void 
1d3c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
1d3d0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
1d3e0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
1d3f0 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
1d400 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
1d410 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
1d420 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
1d430 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1d440 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
1d450 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
1d460 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 52  allbacks.**.** R
1d470 65 67 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61  egister a callba
1d480 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ck function with
1d490 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d4a0 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66  nnection identif
1d4b0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
1d4c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1d4d0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
1d4e0 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70  ever a row is up
1d4f0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
1d500 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41  or deleted..** A
1d510 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
1d520 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
1d530 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
1d540 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ion for the same
1d550 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f   .** database co
1d560 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
1d570 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  ridden..**.** Th
1d580 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1d590 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
1d5a0 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
1d5b0 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20  o invoke when a 
1d5c0 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74  .** row is updat
1d5d0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
1d5e0 64 65 6c 65 74 65 64 2e 20 54 68 65 20 66 69 72  deleted. The fir
1d5f0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1d600 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a  he callback is.*
1d610 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  * a copy of the 
1d620 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
1d630 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
1d640 5f 68 6f 6f 6b 28 29 2e 20 54 68 65 20 73 65 63  _hook(). The sec
1d650 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a  ond callback .**
1d660 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
1d670 20 6f 66 20 53 51 4c 49 54 45 5f 49 4e 53 45 52   of SQLITE_INSER
1d680 54 2c 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  T, SQLITE_DELETE
1d690 20 6f 72 20 53 51 4c 49 54 45 5f 55 50 44 41 54   or SQLITE_UPDAT
1d6a0 45 2c 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  E, depending.** 
1d6b0 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
1d6c0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
1d6d0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
1d6e0 69 6e 76 6f 6b 65 64 2e 20 54 68 65 20 74 68 69  invoked. The thi
1d6f0 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74  rd and .** fourt
1d700 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
1d710 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
1d720 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ain pointers to 
1d730 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1d740 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20   .** table name 
1d750 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
1d760 66 66 65 63 74 65 64 20 72 6f 77 2e 20 54 68 65  ffected row. The
1d770 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
1d780 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a  parameter is .**
1d790 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
1d7a0 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 61  e row. In the ca
1d7b0 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
1d7c0 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77   this is the row
1d7d0 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 65  id after .** the
1d7e0 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
1d7f0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ace..**.** The u
1d800 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
1d810 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
1d820 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
1d830 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
1d840 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
1d850 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
1d860 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a  lite_sequence)..
1d870 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
1d880 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
1d890 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
1d8a0 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61  red, its pArg va
1d8b0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
1d8c0 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 4e 55  .** Otherwise NU
1d8d0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
1d8e0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1d8f0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
1d900 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
1d910 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
1d920 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
1d930 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
1d940 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
1d950 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
1d960 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f  I3REF:  Enable O
1d970 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
1d980 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 0a   Pager Cache.**.
1d990 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1d9a0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
1d9b0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
1d9c0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1d9d0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
1d9e0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
1d9f0 72 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e  res between conn
1da00 65 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73  ections to the s
1da10 61 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  ame database..**
1da20 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   Sharing is enab
1da30 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
1da40 65 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64 20  ent is true and 
1da50 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
1da60 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66  argument.** is f
1da70 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 42 65 67 69  alse..**.** Begi
1da80 6e 6e 69 6e 67 20 69 6e 20 53 51 4c 69 74 65 20  nning in SQLite 
1da90 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 63  version 3.5.0, c
1daa0 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20  ache sharing is 
1dab0 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61  enabled and disa
1dac0 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65  bled.** for an e
1dad0 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 20  ntire process.  
1dae0 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
1daf0 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61  s of SQLite, sha
1db00 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62  ring was.** enab
1db10 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
1db20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
1db30 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
1db40 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72  * The cache shar
1db50 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
1db60 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
1db70 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
1db80 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
1db90 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1dba0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1dbb0 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
1dbc0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
1dbd0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74  .** Existing dat
1dbe0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1dbf0 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
1dc00 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
1dc10 74 68 61 74 20 77 61 73 0a 2a 2a 20 69 6e 20 65  that was.** in e
1dc20 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
1dc30 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
1dc40 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ed..**.** Virtua
1dc50 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20  l tables cannot 
1dc60 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73  be used with a s
1dc70 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68  hared cache.  Wh
1dc80 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  en shared.** cac
1dc90 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74  he is enabled, t
1dca0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
1dcb0 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49  te_module()] API
1dcc0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
1dcd0 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  r.** virtual tab
1dce0 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  les will always 
1dcf0 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
1dd00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1dd10 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
1dd20 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
1dd30 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a 20 65  d cache was.** e
1dd40 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
1dd50 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ed successfully.
1dd60 20 20 41 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52    An [SQLITE_ERR
1dd70 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d  OR | error code]
1dd80 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1dd90 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
1dda0 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73   Shared cache is
1ddb0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1ddc0 61 75 6c 74 2e 20 20 42 75 74 20 74 68 69 73 20  ault.  But this 
1ddd0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a  might change in.
1dde0 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ** future releas
1ddf0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  es of SQLite.  A
1de00 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1de10 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72   care about shar
1de20 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74  ed.** cache sett
1de30 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69  ing should set i
1de40 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2f  t explicitly..*/
1de50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
1de60 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
1de70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
1de80 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74  PI3REF:  Attempt
1de90 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
1dea0 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d  mory.**.** Attem
1deb0 70 74 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74  pt to free N byt
1dec0 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  es of heap memor
1ded0 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
1dee0 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a  g non-essential.
1def0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
1df00 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68  tions held by th
1df10 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
1df20 72 79 20 28 65 78 61 6d 70 6c 65 3a 20 6d 65 6d  ry (example: mem
1df30 6f 72 79 20 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ory .** used to 
1df40 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20 70  cache database p
1df50 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20  ages to improve 
1df60 70 65 72 66 6f 72 6d 61 6e 63 65 29 2e 0a 2a 2f  performance)..*/
1df70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
1df80 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
1df90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1dfa0 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  F:  Impose A Lim
1dfb0 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a  it On Heap Size.
1dfc0 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20 61 20 22 73  **.** Place a "s
1dfd0 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68  oft" limit on th
1dfe0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
1dff0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
1e000 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a   be allocated.**
1e010 20 62 79 20 53 51 4c 69 74 65 2e 20 20 49 66 20   by SQLite.  If 
1e020 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
1e030 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
1e040 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 77 6f 75  ted .** that wou
1e050 6c 64 20 65 78 63 65 65 64 20 74 68 65 20 73 70  ld exceed the sp
1e060 65 63 69 66 69 65 64 20 6c 69 6d 69 74 2c 20 5b  ecified limit, [
1e070 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
1e080 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a 2a 20  memory()] is.** 
1e090 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 20 6d  invoked one or m
1e0a0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65  ore times to fre
1e0b0 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20  e up some space 
1e0c0 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63  before the alloc
1e0d0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61 64 65  ation.** is made
1e0e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69  ..**.** The limi
1e0f0 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66  t is called "sof
1e100 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b  t", because if [
1e110 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
1e120 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e 6e 6f 74  memory()] cannot
1e130 0a 2a 2a 20 66 72 65 65 20 73 75 66 66 69 63 69  .** free suffici
1e140 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72  ent memory to pr
1e150 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20  event the limit 
1e160 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65  from being excee
1e170 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  ded,.** the memo
1e180 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20  ry is allocated 
1e190 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63  anyway and the c
1e1a0 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
1e1b0 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a   proceeds..**.**
1e1c0 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a   A negative or z
1e1d0 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
1e1e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
1e1f0 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
1e200 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
1e210 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
1e220 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
1e230 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
1e240 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
1e250 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65  usted..** The de
1e260 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20  fault value for 
1e270 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
1e280 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  mit is zero..**.
1e290 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
1e2a0 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f  a best effort to
1e2b0 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20   honor the soft 
1e2c0 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 42 75 74  heap limit.  But
1e2d0 20 69 66 20 69 74 0a 2a 2a 20 69 73 20 75 6e 61   if it.** is una
1e2e0 62 6c 65 20 74 6f 20 72 65 64 75 63 65 20 6d 65  ble to reduce me
1e2f0 6d 6f 72 79 20 75 73 61 67 65 20 62 65 6c 6f 77  mory usage below
1e300 20 74 68 65 20 73 6f 66 74 20 6c 69 6d 69 74 2c   the soft limit,
1e310 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a   execution will.
1e320 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68  ** continue with
1e330 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74  out error or not
1e340 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73  ification.  This
1e350 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69   is why the limi
1e360 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20  t is .** called 
1e370 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
1e380 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
1e390 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  only..**.** The 
1e3a0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
1e3b0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 75  is implemented u
1e3c0 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
1e3d0 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29  3_memory_alarm()
1e3e0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20  ].** interface. 
1e3f0 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 6d   Only a single m
1e400 65 6d 6f 72 79 20 61 6c 61 72 6d 20 69 73 20 61  emory alarm is a
1e410 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
1e420 64 65 66 61 75 6c 74 0a 2a 2a 20 69 6d 70 6c 65  default.** imple
1e430 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 69 73  mentation.  This
1e440 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
1e450 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 61  he application a
1e460 6c 73 6f 20 75 73 65 73 20 74 68 65 0a 2a 2a 20  lso uses the.** 
1e470 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20 69 6e 74  memory alarm int
1e480 65 72 66 61 63 65 20 69 74 20 77 69 6c 6c 20 69  erface it will i
1e490 6e 74 65 72 66 65 72 65 20 77 69 74 68 20 74 68  nterfere with th
1e4a0 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
1e4b0 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20  he.** soft heap 
1e4c0 6c 69 6d 69 74 20 61 6e 64 20 75 6e 64 65 66 69  limit and undefi
1e4d0 6e 65 64 20 62 65 68 61 76 69 6f 72 20 77 69 6c  ned behavior wil
1e4e0 6c 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 0a 2a  l result.  .**.*
1e4f0 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
1e500 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c  e version 3.5.0,
1e510 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e   this routine on
1e520 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74  ly constrained t
1e530 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
1e540 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67  ocated by a sing
1e550 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20  le thread - the 
1e560 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
1e570 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e  hich this routin
1e580 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69  e.** runs.  Begi
1e590 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74  nning with SQLit
1e5a0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c  e version 3.5.0,
1e5b0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
1e5c0 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69  imit is.** appli
1e5d0 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64  ed to all thread
1e5e0 73 2e 20 20 54 68 65 20 76 61 6c 75 65 20 73 70  s.  The value sp
1e5f0 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 20  ecified for the 
1e600 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a  soft heap limit.
1e610 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 62  ** is an upper b
1e620 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61  ound on the tota
1e630 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1e640 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ion for all thre
1e650 61 64 73 2e 20 20 49 6e 0a 2a 2a 20 76 65 72 73  ads.  In.** vers
1e660 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20  ion 3.5.0 there 
1e670 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20  is no mechanism 
1e680 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65  for limiting the
1e690 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a   heap usage for.
1e6a0 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68  ** individual th
1e6b0 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73  reads..*/.void s
1e6c0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
1e6d0 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a  _limit(int);../*
1e6e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
1e6f0 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20  xtract Metadata 
1e700 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f  About A Column O
1e710 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  f A Table.**.** 
1e720 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  This routine.** 
1e730 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74  returns meta-dat
1e740 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
1e750 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
1e760 70 65 63 69 66 69 63 20 64 61 74 61 62 61 73 65  pecific database
1e770 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73  .** table access
1e780 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63  ible using the c
1e790 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
1e7a0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
1e7b0 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a  irst function .*
1e7c0 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  * argument..**.*
1e7d0 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  * The column is 
1e7e0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
1e7f0 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
1e800 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
1e810 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69  eters to .** thi
1e820 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  s function. The 
1e830 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1e840 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
1e850 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1e860 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
1e870 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61  in", "temp" or a
1e880 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
1e890 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
1e8a0 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
1e8b0 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
1e8c0 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
1e8d0 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64  hen all attached
1e8e0 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73   databases are s
1e8f0 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74  earched.** for t
1e900 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74  he table using t
1e910 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
1e920 6d 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  m as the databas
1e930 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f  e engine uses to
1e940 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71   .** resolve unq
1e950 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
1e960 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
1e970 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
1e980 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
1e990 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
1e9a0 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20  n are the table 
1e9b0 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e  and column .** n
1e9c0 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
1e9d0 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
1e9e0 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
1e9f0 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
1ea00 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20  ters .** may be 
1ea10 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61  NULL..**.** Meta
1ea20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1ea30 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
1ea40 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
1ea50 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
1ea60 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68  ed as.** the 5th
1ea70 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
1ea80 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1ea90 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79  is function. Any
1eaa0 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72   of these .** ar
1eab0 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e  guments may be N
1eac0 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
1ead0 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
1eae0 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
1eaf0 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61  meta .** informa
1eb00 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64  tion is ommitted
1eb10 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  ..**.** <pre>.**
1eb20 20 50 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f   Parameter     O
1eb30 75 74 70 75 74 20 54 79 70 65 20 20 20 20 20 20  utput Type      
1eb40 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d  Description.** -
1eb50 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1eb60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1eb70 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20  --.**.**   5th  
1eb80 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61         const cha
1eb90 72 2a 20 20 20 20 20 20 44 61 74 61 20 74 79 70  r*      Data typ
1eba0 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20  e.**   6th      
1ebb0 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20     const char*  
1ebc0 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20      Name of the 
1ebd0 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f  default collatio
1ebe0 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20  n sequence .**  
1ebf0 20 37 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   7th         int
1ec00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
1ec10 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
1ec20 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
1ec30 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20  constraint.**   
1ec40 38 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  8th         int 
1ec50 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
1ec60 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
1ec70 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
1ec80 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20  RIMARY KEY.**   
1ec90 39 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  9th         int 
1eca0 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
1ecb0 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
1ecc0 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54  is AUTOINCREMENT
1ecd0 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
1ece0 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70  .** The memory p
1ecf0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
1ed00 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
1ed10 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
1ed20 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61   the .** declara
1ed30 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
1ed40 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1ed50 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
1ed60 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a  ntil the next .*
1ed70 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71  * call to any sq
1ed80 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f  lite API functio
1ed90 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
1eda0 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
1edb0 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
1edc0 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f  ew, then an erro
1edd0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1ede0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
1edf0 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
1ee00 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
1ee10 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
1ee20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50  an .** INTEGER P
1ee30 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d  RIMARY KEY colum
1ee40 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
1ee50 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
1ee60 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20  then the output 
1ee70 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
1ee80 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
1ee90 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
1eea0 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68  ed column. If th
1eeb0 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
1eec0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
1eed0 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65   IPK column, the
1eee0 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70 61 72  n the output par
1eef0 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
1ef00 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a  as .** follows:.
1ef10 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
1ef20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
1ef30 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
1ef40 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
1ef50 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
1ef60 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
1ef70 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
1ef80 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
1ef90 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
1efa0 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68   </pre>.**.** Th
1efb0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
1efc0 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
1efd0 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
1efe0 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
1eff0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
1f000 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
1f010 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
1f020 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
1f030 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
1f040 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
1f050 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72   an SQLITE error
1f060 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
1f070 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
1f080 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69  essage.** left i
1f090 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  n the database h
1f0a0 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74  andle (to be ret
1f0b0 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
1f0c0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a  ite3_errmsg())..
1f0d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69  **.** This API i
1f0e0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
1f0f0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
1f100 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1f110 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
1f120 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
1f130 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73  TADATA preproces
1f140 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
1f150 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
1f160 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
1f170 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
1f180 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1f190 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
1f1a0 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
1f1b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
1f1c0 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
1f1d0 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
1f1e0 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
1f1f0 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
1f200 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
1f210 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
1f220 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
1f230 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
1f240 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
1f250 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
1f260 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
1f270 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
1f280 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
1f290 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
1f2a0 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
1f2b0 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
1f2c0 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
1f2d0 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
1f2e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1f2f0 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
1f300 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
1f310 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
1f320 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
1f330 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
1f340 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
1f350 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
1f360 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
1f370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
1f380 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
1f390 66 20 63 6f 6c 75 6d 73 20 69 73 20 61 75 74 6f  f colums is auto
1f3a0 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
1f3b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f3c0 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
1f3d0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70  ion.**.** Attemp
1f3e0 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c  t to load an SQL
1f3f0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
1f400 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
1f410 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a  in the file.** z
1f420 46 69 6c 65 2e 20 20 54 68 65 20 65 6e 74 72 79  File.  The entry
1f430 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e   point is zProc.
1f440 20 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30    zProc may be 0
1f450 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
1f460 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  he.** name of th
1f470 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 64 65  e entry point de
1f480 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74  faults to "sqlit
1f490 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69  e3_extension_ini
1f4a0 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  t"..**.** Return
1f4b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
1f4c0 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
1f4d0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
1f4e0 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
1f4f0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ng..**.** If an 
1f500 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64  error occurs and
1f510 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74   pzErrMsg is not
1f520 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c 20 2a 70   0, then fill *p
1f530 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a  zErrMsg with .**
1f540 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
1f550 65 78 74 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e  ext.  The callin
1f560 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  g function shoul
1f570 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f  d free this memo
1f580 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69 6e 67  ry.** by calling
1f590 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f5a0 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69  ]..**.** Extensi
1f5b0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
1f5c0 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
1f5d0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1f5e0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
1f5f0 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  )].** prior to c
1f600 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20  alling this API 
1f610 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c  or an error will
1f620 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   be returned..*/
1f630 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61  .int sqlite3_loa
1f640 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73  d_extension(.  s
1f650 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1f660 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65       /* Load the
1f670 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20   extension into 
1f680 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f  this database co
1f690 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f  nnection */.  co
1f6a0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
1f6b0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
1f6c0 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72  he shared librar
1f6d0 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74  y containing ext
1f6e0 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ension */.  cons
1f6f0 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20  t char *zProc,  
1f700 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74    /* Entry point
1f710 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20  .  Derived from 
1f720 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20  zFile if 0 */.  
1f730 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20  char **pzErrMsg 
1f740 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72        /* Put err
1f750 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20  or message here 
1f760 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a  if not 0 */.);..
1f770 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f780 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
1f790 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  le Extension Loa
1f7a0 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73  ding.**.** So as
1f7b0 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
1f7c0 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
1f7d0 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
1f7e0 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
1f7f0 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
1f800 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
1f810 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
1f820 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
1f830 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
1f840 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
1f850 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
1f860 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
1f870 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50   following.** AP
1f880 49 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  I is provided to
1f890 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
1f8a0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
1f8b0 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
1f8c0 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 49  n and.** off.  I
1f8d0 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  t is off by defa
1f8e0 75 6c 74 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ult.  See ticket
1f8f0 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 43 61   #1863..**.** Ca
1f900 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1f910 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f  with onoff==1 to
1f920 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
1f930 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e  loading on.** an
1f940 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
1f950 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20  noff==0 to turn 
1f960 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
1f970 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
1f980 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
1f990 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
1f9a0 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
1f9b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f9c0 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65  : Make Arrangeme
1f9d0 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63  nts To Automatic
1f9e0 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74  ally Load An Ext
1f9f0 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 52 65 67  ension.**.** Reg
1fa00 69 73 74 65 72 20 61 6e 20 65 78 74 65 6e 73 69  ister an extensi
1fa10 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74  on entry point t
1fa20 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  hat is automatic
1fa30 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ally invoked.** 
1fa40 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 64  whenever a new d
1fa50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fa60 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69  on is opened usi
1fa70 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ng.** [sqlite3_o
1fa80 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1fa90 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
1faa0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1fab0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  )]..**.** This A
1fac0 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65  PI can be invoke
1fad0 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61  d at program sta
1fae0 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f  rtup in order to
1faf0 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65   register.** one
1fb00 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61   or more statica
1fb10 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e  lly linked exten
1fb20 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20  sions that will 
1fb30 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  be available.** 
1fb40 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62  to all new datab
1fb50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ase connections.
1fb60 0a 2a 2a 0a 2a 2a 20 44 75 70 6c 69 63 61 74 65  .**.** Duplicate
1fb70 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 20   extensions are 
1fb80 64 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c 6c  detected so call
1fb90 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1fba0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
1fbb0 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
1fbc0 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61   extension is ha
1fbd0 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  rmless..**.** Th
1fbe0 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1fbf0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1fc00 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20  he extension in 
1fc10 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74 68 61 74  an array.** that
1fc20 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
1fc30 6d 20 6d 61 6c 6c 6f 63 28 29 2e 20 20 49 66 20  m malloc().  If 
1fc40 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79  you run a memory
1fc50 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72   leak.** checker
1fc60 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d   on your program
1fc70 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20   and it reports 
1fc80 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f  a leak because o
1fc90 66 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c  f this.** array,
1fca0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71   then invoke [sq
1fcb0 6c 69 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f  lite3_automatic_
1fcc0 65 78 74 65 6e 73 69 6f 6e 5f 72 65 73 65 74 28  extension_reset(
1fcd0 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 73  )] prior.** to s
1fce0 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20  hutdown to free 
1fcf0 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a  the memory..**.*
1fd00 2a 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65  * Automatic exte
1fd10 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72  nsions apply acr
1fd20 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  oss all threads.
1fd30 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1fd40 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d  rface is experim
1fd50 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
1fd60 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
1fd70 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20  r.** removal in 
1fd80 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
1fd90 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
1fda0 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65  t sqlite3_auto_e
1fdb0 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78  xtension(void *x
1fdc0 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f  EntryPoint);.../
1fdd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1fde0 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
1fdf0 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
1fe00 0a 2a 2a 0a 2a 2a 20 44 69 73 61 62 6c 65 20 61  .**.** Disable a
1fe10 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
1fe20 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
1fe30 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 20  ic extensions.  
1fe40 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  This.** routine 
1fe50 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
1fe60 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b  t of all prior [
1fe70 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d 61 74 69  sqlite3_automati
1fe80 63 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  c_extension()].*
1fe90 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54  * calls..**.** T
1fea0 68 69 73 20 63 61 6c 6c 20 64 69 73 61 62 6c 65  his call disable
1feb0 64 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65  d automatic exte
1fec0 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68  nsions in all th
1fed0 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  reads..**.** Thi
1fee0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  s interface is e
1fef0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
1ff00 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
1ff10 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76  ange or.** remov
1ff20 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
1ff30 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
1ff40 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1ff50 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
1ff60 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f  nsion(void);.../
1ff70 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d  *.****** EXPERIM
1ff80 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20  ENTAL - subject 
1ff90 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
1ffa0 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a  t notice *******
1ffb0 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  *******.**.** Th
1ffc0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
1ffd0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
1ffe0 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75   mechanism is cu
1fff0 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
20000 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
20010 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
20020 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
20030 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
20040 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
20050 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
20060 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
20070 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
20080 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
20090 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
200a0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
200b0 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 6c   mechanism stabl
200c0 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
200d0 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
200e0 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
200f0 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
20100 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
20110 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
20120 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
20130 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
20140 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
20150 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
20160 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
20170 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
20180 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
20190 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
201a0 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
201b0 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
201c0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
201d0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
201e0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
201f0 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
20200 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
20210 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
20220 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c  ;../*.** A modul
20230 65 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20  e is a class of 
20240 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20  virtual tables. 
20250 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20   Each module is 
20260 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e  defined.** by an
20270 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
20280 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
20290 74 75 72 65 2e 20 20 54 68 69 73 20 73 74 72 75  ture.  This stru
202a0 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a  cture consists.*
202b0 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68  * mostly of meth
202c0 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
202d0 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  le..*/.struct sq
202e0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20  lite3_module {. 
202f0 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
20300 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28   int (*xCreate)(
20310 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
20320 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
20330 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
20340 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
20350 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
20360 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
20370 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
20380 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  r**);.  int (*xC
20390 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a  onnect)(sqlite3*
203a0 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
203b0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
203c0 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
203d0 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
203e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
203f0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
20400 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
20410 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78  int (*xBestIndex
20420 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
20430 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69  pVTab, sqlite3_i
20440 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69  ndex_info*);.  i
20450 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74  nt (*xDisconnect
20460 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
20470 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
20480 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65  xDestroy)(sqlite
20490 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
204a0 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
204b0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
204c0 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62  ab, sqlite3_vtab
204d0 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73  _cursor **ppCurs
204e0 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  or);.  int (*xCl
204f0 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ose)(sqlite3_vta
20500 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
20510 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c  t (*xFilter)(sql
20520 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
20530 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63  *, int idxNum, c
20540 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74  onst char *idxSt
20550 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  r,.             
20560 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c     int argc, sql
20570 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67  ite3_value **arg
20580 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78  v);.  int (*xNex
20590 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  t)(sqlite3_vtab_
205a0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
205b0 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f  (*xEof)(sqlite3_
205c0 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
205d0 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28   int (*xColumn)(
205e0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
205f0 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f  sor*, sqlite3_co
20600 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20  ntext*, int);.  
20610 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71  int (*xRowid)(sq
20620 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
20630 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
20640 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e  4 *pRowid);.  in
20650 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c  t (*xUpdate)(sql
20660 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74  ite3_vtab *, int
20670 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  , sqlite3_value 
20680 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  **, sqlite3_int6
20690 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  4 *);.  int (*xB
206a0 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  egin)(sqlite3_vt
206b0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
206c0 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
206d0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
206e0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74  .  int (*xCommit
206f0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
20700 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
20710 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74  xRollback)(sqlit
20720 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
20730 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75  .  int (*xFindFu
20740 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f  nction)(sqlite3_
20750 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74  vtab *pVtab, int
20760 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61   nArg, const cha
20770 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20  r *zName,.      
20780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20790 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29   void (**pxFunc)
207a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
207b0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
207c0 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20  lue**),.        
207d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
207e0 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20  oid **ppArg);.. 
207f0 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28   int (*xRename)(
20800 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
20810 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  tab, const char 
20820 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  *zNew);.};../*.*
20830 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
20840 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
20850 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74  re and its subst
20860 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64  ructures is used
20870 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
20880 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
20890 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
208a0 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42 65 73  ly from the xBes
208b0 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64  tIndex.** method
208c0 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d   of an sqlite3_m
208d0 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69 65 6c  odule.  The fiel
208e0 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74  ds under **Input
208f0 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69  s** are the.** i
20900 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e  nputs to xBestIn
20910 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64  dex and are read
20920 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64  -only.  xBestInd
20930 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a  ex inserts its.*
20940 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74  * results into t
20950 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66  he **Outputs** f
20960 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ields..**.** The
20970 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
20980 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45  rray records WHE
20990 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
209a0 61 69 6e 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20  aints of the.** 
209b0 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20  form:.**.**     
209c0 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78      column OP ex
209d0 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f  pr.**.** Where O
209e0 50 20 69 73 20 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e  P is =, <, <=, >
209f0 2c 20 6f 72 20 3e 3d 2e 20 20 54 68 65 20 70 61  , or >=.  The pa
20a00 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f  rticular operato
20a10 72 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  r is stored.** i
20a20 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  n aConstraint[].
20a30 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f  op.  The index o
20a40 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
20a50 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43  stored in .** aC
20a60 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c  onstraint[].iCol
20a70 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e  umn.  aConstrain
20a80 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52  t[].usable is TR
20a90 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70  UE if the.** exp
20aa0 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68  r on the right-h
20ab0 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20  and side can be 
20ac0 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74  evaluated (and t
20ad0 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hus the constrai
20ae0 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29  nt.** is usable)
20af0 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74   and false if it
20b00 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54   cannot..**.** T
20b10 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74  he optimizer aut
20b20 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72  omatically inver
20b30 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20  ts terms of the 
20b40 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f  form "expr OP co
20b50 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b  lumn".** and mak
20b60 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66  es other simplif
20b70 69 63 61 74 69 6e 6f 73 20 74 6f 20 74 68 65 20  icatinos to the 
20b80 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20  WHERE clause in 
20b90 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  an attempt to.**
20ba0 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45   get as many WHE
20bb0 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20  RE clause terms 
20bc0 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68  into the form sh
20bd0 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73  own above as pos
20be0 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43  sible..** The aC
20bf0 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
20c00 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57  y only reports W
20c10 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
20c20 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74  s in the correct
20c30 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65  .** form that re
20c40 66 65 72 20 74 6f 20 74 68 65 20 70 61 72 74 69  fer to the parti
20c50 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61  cular virtual ta
20c60 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65  ble being querie
20c70 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61  d..**.** Informa
20c80 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f  tion about the O
20c90 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69  RDER BY clause i
20ca0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64  s stored in aOrd
20cb0 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20  erBy[]..** Each 
20cc0 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79  term of aOrderBy
20cd0 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d   records a colum
20ce0 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42  n of the ORDER B
20cf0 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  Y clause..**.** 
20d00 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d  The xBestIndex m
20d10 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
20d20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
20d30 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
20d40 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
20d50 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
20d60 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
20d70 20 20 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30    If argvIndex>0
20d80 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67   then.** the rig
20d90 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ht-hand side of 
20da0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
20db0 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  g aConstraint[] 
20dc0 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20  is evaluated.** 
20dd0 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  and becomes the 
20de0 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74  argvIndex-th ent
20df0 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20  ry in argv.  If 
20e00 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
20e10 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72  [].omit.** is tr
20e20 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  ue, then the con
20e30 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d  straint is assum
20e40 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68  ed to be fully h
20e50 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  andled by the.**
20e60 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
20e70 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65  nd is not checke
20e80 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74  d again by SQLit
20e90 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78  e..**.** The idx
20ea0 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76  Num and idxPtr v
20eb0 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64  alues are record
20ec0 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e  ed and passed in
20ed0 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73  to xFilter..** s
20ee0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
20ef0 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64   used to free id
20f00 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f 46 72  xPtr if needToFr
20f10 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65  eeIdxPtr is true
20f20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65  ..**.** The orde
20f30 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e  rByConsumed mean
20f40 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72  s that output fr
20f50 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c 6c 20  om xFilter will 
20f60 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20  occur in.** the 
20f70 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f  correct order to
20f80 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44   satisfy the ORD
20f90 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20  ER BY clause so 
20fa0 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65  that no separate
20fb0 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70  .** sorting step
20fc0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
20fd0 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74 65  .** The estimate
20fe0 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61  dCost value is a
20ff0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68  n estimate of th
21000 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20  e cost of doing 
21010 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  the.** particula
21020 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c  r lookup.  A ful
21030 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c  l scan of a tabl
21040 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73  e with N entries
21050 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20   should have.** 
21060 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20  a cost of N.  A 
21070 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66  binary search of
21080 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e   a table of N en
21090 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
210a0 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61  e a.** cost of a
210b0 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67  pproximately log
210c0 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  (N)..*/.struct s
210d0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
210e0 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20  o {.  /* Inputs 
210f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e  */.  const int n
21100 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
21110 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74  /* Number of ent
21120 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61  ries in aConstra
21130 69 6e 74 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  int */.  const s
21140 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
21150 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b  dex_constraint {
21160 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
21170 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
21180 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66  /* Column on lef
21190 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63  t-hand side of c
211a0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20  onstraint */.   
211b0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
211c0 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43  op;         /* C
211d0 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74  onstraint operat
211e0 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  or */.     unsig
211f0 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
21200 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
21210 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
21220 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20  is usable */.   
21230 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65    int iTermOffse
21240 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55  t;          /* U
21250 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d  sed internally -
21260 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75   xBestIndex shou
21270 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d  ld ignore */.  }
21280 20 2a 63 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61   *const aConstra
21290 69 6e 74 3b 20 20 20 20 20 20 2f 2a 20 54 61 62  int;      /* Tab
212a0 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75  le of WHERE clau
212b0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a  se constraints *
212c0 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e 4f  /.  const int nO
212d0 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 2f  rderBy;        /
212e0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  * Number of term
212f0 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42  s in the ORDER B
21300 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 63 6f  Y clause */.  co
21310 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
21320 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79  e3_index_orderby
21330 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
21340 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
21350 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62    /* Column numb
21360 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  er */.     unsig
21370 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20  ned char desc;  
21380 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72       /* True for
21390 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f   DESC.  False fo
213a0 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 63  r ASC. */.  } *c
213b0 6f 6e 73 74 20 61 4f 72 64 65 72 42 79 3b 20 20  onst aOrderBy;  
213c0 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52         /* The OR
213d0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
213e0 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a  ..  /* Outputs *
213f0 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
21400 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
21410 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20  int_usage {.    
21420 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20  int argvIndex;  
21430 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e           /* if >
21440 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  0, constraint is
21450 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f   part of argv to
21460 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20   xFilter */.    
21470 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d  unsigned char om
21480 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e  it;      /* Do n
21490 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66  ot code a test f
214a0 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  or this constrai
214b0 6e 74 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74  nt */.  } *const
214c0 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
214d0 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
214e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
214f0 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
21500 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
21510 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
21520 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
21530 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
21540 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
21550 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
21560 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
21570 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
21580 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
21590 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
215a0 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
215b0 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
215c0 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
215d0 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
215e0 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
215f0 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
21600 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
21610 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
21620 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
21630 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
21640 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  };.#define SQLIT
21650 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
21660 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69  NT_EQ    2.#defi
21670 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
21680 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20  CONSTRAINT_GT   
21690 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
216a0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
216b0 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69  NT_LE    8.#defi
216c0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
216d0 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
216e0 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
216f0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
21700 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65  INT_GE    32.#de
21710 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
21720 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
21730 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69  CH 64../*.** Thi
21740 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65  s routine is use
21750 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20  d to register a 
21760 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20  new module name 
21770 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65 0a 2a  with an SQLite.*
21780 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d  * connection.  M
21790 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74  odule names must
217a0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62   be registered b
217b0 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67 20 6e  efore creating n
217c0 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  ew.** virtual ta
217d0 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75  bles on the modu
217e0 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75 73  le, or before us
217f0 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e 67 20  ing preexisting 
21800 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
21810 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  s of the module.
21820 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
21830 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20  create_module(. 
21840 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
21850 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
21860 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
21870 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
21880 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
21890 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
218a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
218b0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
218c0 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
218d0 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f  3_module *,    /
218e0 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
218f0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
21900 69 64 20 2a 20 20 20 20 20 20 20 20 20 20 20 20  id *            
21910 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
21920 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
21930 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
21940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72  );../*.** This r
21950 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e 74 69  outine is identi
21960 63 61 6c 20 74 6f 20 74 68 65 20 73 71 6c 69 74  cal to the sqlit
21970 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
21980 28 29 20 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c  () method above,
21990 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
219a0 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65 73 74  it allows a dest
219b0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
219c0 74 6f 20 62 65 20 73 70 65 63 69 66 69 65 64 2e  to be specified.
219d0 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d   It is.** even m
219e0 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  ore experimental
219f0 20 74 68 61 6e 20 74 68 65 20 72 65 73 74 20 6f   than the rest o
21a00 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
21a10 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74  bles API..*/.int
21a20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
21a30 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c  module_v2(.  sql
21a40 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
21a50 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
21a60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
21a70 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
21a80 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
21a90 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
21aa0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
21ab0 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
21ac0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
21ad0 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65  dule *,    /* Me
21ae0 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
21af0 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
21b00 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
21b10 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
21b20 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
21b30 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f  xConnect */.  vo
21b40 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
21b50 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75  id*)     /* Modu
21b60 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  le destructor fu
21b70 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a  nction */.);../*
21b80 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65  .** Every module
21b90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
21ba0 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
21bb0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
21bc0 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f   structure.** to
21bd0 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
21be0 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20  icular instance 
21bf0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
21c00 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69  Each subclass wi
21c10 6c 6c 0a 2a 2a 20 62 65 20 74 61 79 6c 6f 72 65  ll.** be taylore
21c20 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  d to the specifi
21c30 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d  c needs of the m
21c40 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
21c50 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a 2a 20 70  tion.   The.** p
21c60 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73  urpose of this s
21c70 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20  uperclass is to 
21c80 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66  define certain f
21c90 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 20 63  ields that are c
21ca0 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20  ommon.** to all 
21cb0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
21cc0 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69  ations..**.** Vi
21cd0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74  rtual tables met
21ce0 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20  hods can set an 
21cf0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79  error message by
21d00 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20   assigning a.** 
21d10 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
21d20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
21d30 69 6e 74 66 28 29 20 74 6f 20 7a 45 72 72 4d 73  intf() to zErrMs
21d40 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73  g.  The method s
21d50 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61  hould.** take ca
21d60 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f  re that any prio
21d70 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65  r string is free
21d80 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 73  d by a call to s
21d90 71 6c 69 74 65 33 5f 66 72 65 65 28 29 0a 2a 2a  qlite3_free().**
21da0 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e   prior to assign
21db0 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67  ing a new string
21dc0 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66   to zErrMsg.  Af
21dd0 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
21de0 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
21df0 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
21e00 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
21e10 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
21e20 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
21e30 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
21e40 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
21e50 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
21e60 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
21e70 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74  roed.  Note.** t
21e80 68 61 74 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  hat sqlite3_mpri
21e90 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
21ea0 33 5f 66 72 65 65 28 29 20 61 72 65 20 75 73 65  3_free() are use
21eb0 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 4d 73 67  d on the zErrMsg
21ec0 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20   field.** since 
21ed0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 61  virtual tables a
21ee0 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c  re commonly impl
21ef0 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61  emented in loada
21f00 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 77  ble extensions w
21f10 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68  hich.** do not h
21f20 61 76 65 20 61 63 63 65 73 73 20 74 6f 20 73 71  ave access to sq
21f30 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 29 20 6f  lite3MPrintf() o
21f40 72 20 73 71 6c 69 74 65 33 46 72 65 65 28 29 2e  r sqlite3Free().
21f50 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
21f60 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73  e3_vtab {.  cons
21f70 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
21f80 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54   *pModule;  /* T
21f90 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68  he module for th
21fa0 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  is virtual table
21fb0 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20   */.  int nRef; 
21fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21fd0 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e        /* Used in
21fe0 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68  ternally */.  ch
21ff0 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20  ar *zErrMsg;    
22000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
22010 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66   Error message f
22020 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  rom sqlite3_mpri
22030 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69  ntf() */.  /* Vi
22040 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
22050 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
22060 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
22070 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
22080 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76 65 72 79   */.};../* Every
22090 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
220a0 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
220b0 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f  bclass of the fo
220c0 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
220d0 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65  e.** to describe
220e0 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f   cursors that po
220f0 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 69 72  int into the vir
22100 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 61  tual table and a
22110 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
22120 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
22130 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
22140 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
22150 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
22160 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20  xOpen method of 
22170 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63  the module.  Eac
22180 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  h module impleme
22190 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66  ntation will def
221a0 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65  ine.** the conte
221b0 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73  nt of a cursor s
221c0 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74  tructure to suit
221d0 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a   its own needs..
221e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72  **.** This super
221f0 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20  class exists in 
22200 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20  order to define 
22210 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75  fields of the cu
22220 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65  rsor that.** are
22230 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69   common to all i
22240 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
22250 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
22260 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a  3_vtab_cursor {.
22270 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
22280 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56  pVtab;      /* V
22290 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20  irtual table of 
222a0 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20  this cursor */. 
222b0 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
222c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
222d0 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  s will typically
222e0 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
222f0 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  fields */.};../*
22300 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74 65 20  .** The xCreate 
22310 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74  and xConnect met
22320 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65  hods of a module
22330 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69   use the followi
22340 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63  ng API.** to dec
22350 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20  lare the format 
22360 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64  (the names and d
22370 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20  atatypes of the 
22380 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74  columns) of.** t
22390 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
223a0 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74  s they implement
223b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
223c0 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71  _declare_vtab(sq
223d0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
223e0 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62 6c 65  ar *zCreateTable
223f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72 74 75 61  );../*.** Virtua
22400 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f  l tables can pro
22410 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65  vide alternative
22420 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
22430 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
22440 20 75 73 69 6e 67 20 74 68 65 20 78 46 69 6e 64   using the xFind
22450 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e  Function method.
22460 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72    But global ver
22470 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66  sions of those f
22480 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  unctions.** must
22490 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20   exist in order 
224a0 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  to be overloaded
224b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
224c0 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
224d0 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
224e0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
224f0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
22500 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
22510 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
22520 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
22530 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
22540 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
22550 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
22560 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
22570 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
22580 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
22590 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
225a0 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
225b0 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
225c0 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
225d0 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
225e0 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
225f0 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
22600 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
22610 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
22620 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
22630 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e  -holder function
22640 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
22650 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76 69  rloaded.** by vi
22660 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a  rtual tables..**
22670 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73 68 6f  .** This API sho
22680 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72 65  uld be considere
22690 64 20 70 61 72 74 20 6f 66 20 74 68 65 20 76 69  d part of the vi
226a0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
226b0 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20  rface,.** which 
226c0 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  is experimental 
226d0 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20 63  and subject to c
226e0 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
226f0 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66  lite3_overload_f
22700 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a  unction(sqlite3*
22710 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
22720 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72  uncName, int nAr
22730 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69  g);../*.** The i
22740 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
22750 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
22760 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20  chanism defined 
22770 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a  above (back up.*
22780 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72  * to a comment r
22790 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61  emarkably simila
227a0 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69  r to this one) i
227b0 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
227c0 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
227d0 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
227e0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
227f0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
22800 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
22810 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
22820 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
22830 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
22840 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
22850 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
22860 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
22870 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
22880 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  tablizes, we wil
22890 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
228a0 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
228b0 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
228c0 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
228d0 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
228e0 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58  nt..**.****** EX
228f0 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62  PERIMENTAL - sub
22900 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77  ject to change w
22910 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a  ithout notice **
22920 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a  ************.*/.
22930 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22940 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20   A Handle To An 
22950 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20  Open BLOB.**.** 
22960 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
22970 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 70 61  he following opa
22980 71 75 65 20 73 74 72 75 63 74 75 72 65 20 69 73  que structure is
22990 20 75 73 65 64 20 74 6f 20 0a 2a 2a 20 72 65 70   used to .** rep
229a0 72 65 73 65 6e 74 20 61 6e 20 62 6c 6f 62 2d 68  resent an blob-h
229b0 61 6e 64 6c 65 2e 20 20 41 20 62 6c 6f 62 2d 68  andle.  A blob-h
229c0 61 6e 64 6c 65 20 69 73 20 63 72 65 61 74 65 64  andle is created
229d0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
229e0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  blob_open()] and
229f0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
22a00 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
22a10 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
22a20 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
22a30 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
22a40 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e  blob_write()] in
22a50 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20  terfaces.** can 
22a60 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20  be used to read 
22a70 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73  or write small s
22a80 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68  ubsections of th
22a90 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b  e blob..** The [
22aa0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
22ab0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
22ac0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
22ad0 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c 6f 62 20   of the.** blob 
22ae0 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70  in bytes..*/.typ
22af0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
22b00 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33  te3_blob sqlite3
22b10 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _blob;../*.** CA
22b20 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42  PI3REF: Open A B
22b30 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e  LOB For Incremen
22b40 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 4f 70  tal I/O.**.** Op
22b50 65 6e 20 61 20 68 61 6e 64 6c 65 20 74 6f 20 74  en a handle to t
22b60 68 65 20 62 6c 6f 62 20 6c 6f 63 61 74 65 64 20  he blob located 
22b70 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20 63 6f  in row iRow,, co
22b80 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 0a 2a  lumn zColumn, .*
22b90 2a 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69  * table zTable i
22ba0 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 2e 20  n database zDb. 
22bb0 69 2e 65 2e 20 74 68 65 20 73 61 6d 65 20 62 6c  i.e. the same bl
22bc0 6f 62 20 74 68 61 74 20 77 6f 75 6c 64 0a 2a 2a  ob that would.**
22bd0 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a   be selected by:
22be0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
22bf0 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75      SELECT zColu
22c00 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62  mn FROM zDb.zTab
22c10 6c 65 20 57 48 45 52 45 20 72 6f 77 69 64 20 3d  le WHERE rowid =
22c20 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   iRow;.** </pre>
22c30 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c  .**.** If the fl
22c40 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  ags parameter is
22c50 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 62   non-zero, the b
22c60 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  lob is opened fo
22c70 72 20 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20 77  r .** read and w
22c80 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20  rite access. If 
22c90 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
22ca0 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66  blob is opened f
22cb0 6f 72 20 72 65 61 64 20 0a 2a 2a 20 61 63 63 65  or read .** acce
22cc0 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  ss..**.** On suc
22cd0 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  cess, [SQLITE_OK
22ce0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
22cf0 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73  d the new .** [s
22d00 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
22d10 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72  ob handle] is wr
22d20 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62  itten to *ppBlob
22d30 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 61  ..** Otherwise a
22d40 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  n error code is 
22d50 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a 2a  returned and .**
22d60 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74 74   any value writt
22d70 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68  en to *ppBlob sh
22d80 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
22d90 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a   by the caller..
22da0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
22db0 20 73 65 74 73 20 74 68 65 20 64 61 74 61 62 61   sets the databa
22dc0 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f 72 20  se-handle error 
22dd0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
22de0 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76  .** accessible v
22df0 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
22e00 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ode()] and [sqli
22e10 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
22e20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
22e30 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74  ob_open(.  sqlit
22e40 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  e3*,.  const cha
22e50 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20  r *zDb,.  const 
22e60 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20  char *zTable,.  
22e70 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
22e80 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69  umn,.  sqlite3_i
22e90 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74  nt64 iRow,.  int
22ea0 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65   flags,.  sqlite
22eb0 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a  3_blob **ppBlob.
22ec0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22ed0 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 4c 4f  EF:  Close A BLO
22ee0 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 43  B Handle.**.** C
22ef0 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b 73 71  lose an open [sq
22f00 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f  lite3_blob | blo
22f10 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2f 0a 69 6e  b handle]..*/.in
22f20 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63  t sqlite3_blob_c
22f30 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  lose(sqlite3_blo
22f40 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
22f50 49 33 52 45 46 3a 20 20 52 65 74 75 72 6e 20 54  I3REF:  Return T
22f60 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70  he Size Of An Op
22f70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 52 65  en BLOB.**.** Re
22f80 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 69 6e  turn the size in
22f90 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c   bytes of the bl
22fa0 6f 62 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ob accessible vi
22fb0 61 20 74 68 65 20 6f 70 65 6e 20 0a 2a 2a 20 5b  a the open .** [
22fc0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
22fd0 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73  lob-handle] pass
22fe0 65 64 20 61 73 20 61 6e 20 61 72 67 75 6d 65 6e  ed as an argumen
22ff0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
23000 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c  3_blob_bytes(sql
23010 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
23020 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
23030 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41  Read Data From A
23040 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61   BLOB Incrementa
23050 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  lly.**.** This f
23060 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20  unction is used 
23070 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f  to read data fro
23080 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73  m an open .** [s
23090 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
230a0 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20  ob-handle] into 
230b0 61 20 63 61 6c 6c 65 72 20 73 75 70 70 6c 69 65  a caller supplie
230c0 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20 62  d buffer..** n b
230d0 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
230e0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66   copied into buf
230f0 66 65 72 0a 2a 2a 20 7a 20 66 72 6f 6d 20 74 68  fer.** z from th
23100 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61  e open blob, sta
23110 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20  rting at offset 
23120 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 4f  iOffset..**.** O
23130 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54  n success, SQLIT
23140 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
23150 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20  . Otherwise, an 
23160 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
23170 52 20 7c 20 53 51 4c 69 74 65 20 65 72 72 6f 72  R | SQLite error
23180 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
23190 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
231a0 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72  AD | extended er
231b0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
231c0 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  urned..*/.int sq
231d0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
231e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
231f0 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20  void *z, int n, 
23200 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f  int iOffset);../
23210 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
23220 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20  Write Data Into 
23230 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
23240 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ally.**.** This 
23250 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
23260 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69   to write data i
23270 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20  nto an open .** 
23280 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
23290 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 66 72 6f  blob-handle] fro
232a0 6d 20 61 20 75 73 65 72 20 73 75 70 70 6c 69 65  m a user supplie
232b0 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20 62  d buffer..** n b
232c0 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
232d0 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65   copied from the
232e0 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69 6e 74   buffer.** point
232f0 65 64 20 74 6f 20 62 79 20 7a 20 69 6e 74 6f 20  ed to by z into 
23300 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73  the open blob, s
23310 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
23320 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a  t iOffset..**.**
23330 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
23340 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e  _blob | blob-han
23350 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 74  dle] passed as t
23360 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
23370 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 70 65  t.** was not ope
23380 6e 65 64 20 66 6f 72 20 77 72 69 74 69 6e 67 20  ned for writing 
23390 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (the flags param
233a0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
233b0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  _blob_open()].**
233c0 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20 74 68 69  * was zero), thi
233d0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
233e0 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f  ns [SQLITE_READO
233f0 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  NLY]..**.** This
23400 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e   function may on
23410 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f  ly modify the co
23420 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 62 6c  ntents of the bl
23430 6f 62 2c 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74  ob, it is.** not
23440 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63   possible to inc
23450 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f  rease the size o
23460 66 20 61 20 62 6c 6f 62 20 75 73 69 6e 67 20 74  f a blob using t
23470 68 69 73 20 41 50 49 2e 20 49 66 0a 2a 2a 20 6f  his API. If.** o
23480 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73  ffset iOffset is
23490 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62 79 74   less than n byt
234a0 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20  es from the end 
234b0 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a  of the blob, .**
234c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
234d0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
234e0 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74  no data is writt
234f0 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  en..**.** On suc
23500 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20  cess, SQLITE_OK 
23510 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68  is returned. Oth
23520 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b  erwise, an .** [
23530 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 53  SQLITE_ERROR | S
23540 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65  QLite error code
23550 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49  ] or an.** [SQLI
23560 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
23570 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
23580 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
23590 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
235a0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69  _blob_write(sqli
235b0 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73  te3_blob *, cons
235c0 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e  t void *z, int n
235d0 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a  , int iOffset);.
235e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
235f0 20 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53    Virtual File S
23600 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a  ystem Objects.**
23610 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69  .** A virtual fi
23620 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69  lesystem (VFS) i
23630 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  s an [sqlite3_vf
23640 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61  s] object.** tha
23650 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f  t SQLite uses to
23660 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74   interact.** wit
23670 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  h the underlying
23680 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
23690 6d 2e 20 20 4d 6f 73 74 20 62 75 69 6c 64 73 20  m.  Most builds 
236a0 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73  come with a.** s
236b0 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46  ingle default VF
236c0 53 20 74 68 61 74 20 69 73 20 61 70 70 72 6f 70  S that is approp
236d0 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f  riate for the ho
236e0 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20  st computer..** 
236f0 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 62 65  New VFSes can be
23700 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
23710 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 20 63  existing VFSes c
23720 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65 72  an be unregister
23730 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  ed..** The follo
23740 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20  wing interfaces 
23750 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a  are provided..**
23760 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
23770 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72  vfs_find() inter
23780 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
23790 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20  ointer to a VFS 
237a0 67 69 76 65 6e 20 69 74 73 0a 2a 2a 20 6e 61 6d  given its.** nam
237b0 65 2e 20 20 4e 61 6d 65 73 20 61 72 65 20 63 61  e.  Names are ca
237c0 73 65 20 73 65 6e 73 69 74 69 76 65 2e 20 20 49  se sensitive.  I
237d0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61  f there is no ma
237e0 74 63 68 2c 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  tch, a NULL.** p
237f0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
23800 65 64 2e 20 20 49 66 20 7a 56 66 73 4e 61 6d 65  ed.  If zVfsName
23810 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
23820 65 20 64 65 66 61 75 6c 74 20 0a 2a 2a 20 56 46  e default .** VF
23830 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  S is returned..*
23840 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 61  *.** New VFSes a
23850 72 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  re registered wi
23860 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  th sqlite3_vfs_r
23870 65 67 69 73 74 65 72 28 29 2e 20 20 45 61 63 68  egister().  Each
23880 0a 2a 2a 20 6e 65 77 20 56 46 53 20 62 65 63 6f  .** new VFS beco
23890 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20  mes the default 
238a0 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44  VFS if the makeD
238b0 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e  flt flag is set.
238c0 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20 56 46 53  .** The same VFS
238d0 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
238e0 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
238f0 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79  s without injury
23900 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20  ..** To make an 
23910 65 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74  existing VFS int
23920 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  o the default VF
23930 53 2c 20 72 65 67 69 73 74 65 72 20 69 74 20 61  S, register it a
23940 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  gain.** with the
23950 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73   makeDflt flag s
23960 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66  et.  If two diff
23970 65 72 65 6e 74 20 56 46 53 65 73 20 77 69 74 68  erent VFSes with
23980 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d   the.** same nam
23990 65 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  e are registered
239a0 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
239b0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66  s undefined.  If
239c0 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67   a.** VFS is reg
239d0 69 73 74 65 72 65 64 20 77 69 74 68 20 61 20 6e  istered with a n
239e0 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c  ame that is NULL
239f0 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72   or an empty str
23a00 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ing,.** then the
23a10 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
23a20 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 55  efined..** .** U
23a30 6e 72 65 67 69 73 74 65 72 20 61 20 56 46 53 20  nregister a VFS 
23a40 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33  with the sqlite3
23a50 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
23a60 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  ) interface..** 
23a70 49 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  If the default V
23a80 46 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72  FS is unregister
23a90 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20  ed, another VFS 
23aa0 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20  is chosen as.** 
23ab0 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68  the default.  Th
23ac0 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65  e choice for the
23ad0 20 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69   new VFS is arbi
23ae0 74 72 61 72 79 2e 0a 2a 2f 0a 73 71 6c 69 74 65  trary..*/.sqlite
23af0 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76  3_vfs *sqlite3_v
23b00 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68  fs_find(const ch
23b10 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69  ar *zVfsName);.i
23b20 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  nt sqlite3_vfs_r
23b30 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f  egister(sqlite3_
23b40 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66  vfs*, int makeDf
23b50 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  lt);.int sqlite3
23b60 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
23b70 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a  sqlite3_vfs*);..
23b80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23b90 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Mutexes.**.** Th
23ba0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
23bb0 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  es these routine
23bc0 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20  s for thread.** 
23bd0 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e  synchronization.
23be0 20 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72    Though they ar
23bf0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69  e intended for i
23c00 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62  nternal.** use b
23c10 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74  y SQLite, code t
23c20 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
23c30 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70  t SQLite is.** p
23c40 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20  ermitted to use 
23c50 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
23c60 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
23c70 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
23c80 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c  ode contains mul
23c90 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
23ca0 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66 20 74 68 65  tions .** of the
23cb0 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  se mutex routine
23cc0 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61  s.  An appropria
23cd0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  te implementatio
23ce0 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64  n.** is selected
23cf0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61   automatically a
23d00 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20  t compile-time. 
23d10 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a   The following.*
23d20 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
23d30 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  s are available 
23d40 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  in the SQLite co
23d50 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  re:.**.** <ul>.*
23d60 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
23d70 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69  MUTEX_OS2.** <li
23d80 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
23d90 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e  _PTHREAD.** <li>
23da0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
23db0 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  W32.** <li>   SQ
23dc0 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a  LITE_MUTEX_NOOP.
23dd0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
23de0 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
23df0 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74  NOOP implementat
23e00 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20  ion is a set of 
23e10 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20 74 68 61  routines .** tha
23e20 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c  t does no real l
23e30 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70  ocking and is ap
23e40 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73  propriate for us
23e50 65 20 69 6e 20 0a 2a 2a 20 61 20 73 69 6e 67 6c  e in .** a singl
23e60 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  e-threaded appli
23e70 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c  cation.  The SQL
23e80 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a  ITE_MUTEX_OS2,.*
23e90 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50  * SQLITE_MUTEX_P
23ea0 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49  THREAD, and SQLI
23eb0 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70  TE_MUTEX_W32 imp
23ec0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
23ed0 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  are appropriate 
23ee0 66 6f 72 20 75 73 65 20 6f 6e 20 6f 73 2f 32 2c  for use on os/2,
23ef0 20 75 6e 69 78 2c 20 61 6e 64 20 77 69 6e 64 6f   unix, and windo
23f00 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 53 51  ws..** .** If SQ
23f10 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
23f20 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
23f30 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 72  _MUTEX_APPDEF pr
23f40 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61  eprocessor.** ma
23f50 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74  cro defined (wit
23f60 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45  h "-DSQLITE_MUTE
23f70 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68  X_APPDEF=1"), th
23f80 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69  en no mutex.** i
23f90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
23fa0 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74   included with t
23fb0 68 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  he library.  The
23fc0 0a 2a 2a 20 6d 75 74 65 78 20 69 6e 74 65 72 66  .** mutex interf
23fd0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 64 65 66  ace routines def
23fe0 69 6e 65 64 20 68 65 72 65 20 62 65 63 6f 6d 65  ined here become
23ff0 20 65 78 74 65 72 6e 61 6c 0a 2a 2a 20 72 65 66   external.** ref
24000 65 72 65 6e 63 65 73 20 69 6e 20 74 68 65 20 53  erences in the S
24010 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 66 6f  QLite library fo
24020 72 20 77 68 69 63 68 20 69 6d 70 6c 65 6d 65 6e  r which implemen
24030 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20  tations.** must 
24040 62 65 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  be provided by t
24050 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
24060 20 54 68 69 73 20 66 61 63 69 6c 69 74 79 20 61   This facility a
24070 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20 61 70 70 6c  llows an.** appl
24080 69 63 61 74 69 6f 6e 20 74 68 61 74 20 6c 69 6e  ication that lin
24090 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74  ks against SQLit
240a0 65 20 74 6f 20 70 72 6f 76 69 64 65 20 69 74 73  e to provide its
240b0 20 6f 77 6e 20 6d 75 74 65 78 0a 2a 2a 20 69 6d   own mutex.** im
240c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
240d0 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 6d  hout having to m
240e0 6f 64 69 66 79 20 74 68 65 20 53 51 4c 69 74 65  odify the SQLite
240f0 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   core..**.** The
24100 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
24110 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61  lloc() routine a
24120 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a  llocates a new.*
24130 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75  * mutex and retu
24140 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
24150 20 69 74 2e 20 20 49 66 20 69 74 20 72 65 74 75   it.  If it retu
24160 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74  rns NULL.** that
24170 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75   means that a mu
24180 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  tex could not be
24190 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c   allocated.  SQL
241a0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69  ite.** will unwi
241b0 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64  nd its stack and
241c0 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
241d0 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  .  The argument.
241e0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  ** to sqlite3_mu
241f0 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f  tex_alloc() is o
24200 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
24210 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  ger constants:.*
24220 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
24230 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
24240 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  FAST.** <li>  SQ
24250 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
24260 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
24270 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
24280 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e  C_MASTER.** <li>
24290 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
242a0 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69  TATIC_MEM.** <li
242b0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
242c0 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c  STATIC_MEM2.** <
242d0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
242e0 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a  X_STATIC_PRNG.**
242f0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
24300 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a  TEX_STATIC_LRU.*
24310 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
24320 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73  e first two cons
24330 74 61 6e 74 73 20 63 61 75 73 65 20 73 71 6c 69  tants cause sqli
24340 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
24350 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61  ) to create.** a
24360 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 54 68 65   new mutex.  The
24370 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72 65   new mutex is re
24380 63 75 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c  cursive when SQL
24390 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
243a0 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62  IVE.** is used b
243b0 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69  ut not necessari
243c0 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54  ly so when SQLIT
243d0 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20  E_MUTEX_FAST is 
243e0 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 75 74  used..** The mut
243f0 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ex implementatio
24400 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
24410 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e  to make a distin
24420 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e  ction.** between
24430 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
24440 43 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49  CURSIVE and SQLI
24450 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66  TE_MUTEX_FAST if
24460 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
24470 77 61 6e 74 20 74 6f 2e 20 20 42 75 74 20 53 51  want to.  But SQ
24480 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72  Lite will only r
24490 65 71 75 65 73 74 20 61 20 72 65 63 75 72 73 69  equest a recursi
244a0 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63  ve mutex in.** c
244b0 61 73 65 73 20 77 68 65 72 65 20 69 74 20 72 65  ases where it re
244c0 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20  ally needs one. 
244d0 20 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e   If a faster non
244e0 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78  -recursive mutex
244f0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
24500 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
24510 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74  on the host plat
24520 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20  form, the mutex 
24530 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67  subsystem.** mig
24540 68 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61  ht return such a
24550 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e   mutex in respon
24560 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54  se to SQLITE_MUT
24570 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 54  EX_FAST..**.** T
24580 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64  he other allowed
24590 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73   parameters to s
245a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
245b0 6f 63 28 29 20 65 61 63 68 20 72 65 74 75 72 6e  oc() each return
245c0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
245d0 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69   a static preexi
245e0 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 46 6f  sting mutex.  Fo
245f0 75 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  ur static mutexe
24600 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79  s are.** used by
24610 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72   the current ver
24620 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20  sion of SQLite. 
24630 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
24640 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61   of SQLite.** ma
24650 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
24660 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e   static mutexes.
24670 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73    Static mutexes
24680 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61   are for interna
24690 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
246a0 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63  te only.  Applic
246b0 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
246c0 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73  SQLite mutexes s
246d0 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c  hould.** use onl
246e0 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  y the dynamic mu
246f0 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62  texes returned b
24700 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  y SQLITE_MUTEX_F
24710 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45  AST or.** SQLITE
24720 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
24730 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
24740 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20  t if one of the 
24750 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61  dynamic mutex pa
24760 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45  rameters (SQLITE
24770 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f  _MUTEX_FAST.** o
24780 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  r SQLITE_MUTEX_R
24790 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65  ECURSIVE) is use
247a0 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  d then sqlite3_m
247b0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20  utex_alloc().** 
247c0 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72  returns a differ
247d0 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65  ent mutex on eve
247e0 72 79 20 63 61 6c 6c 2e 20 20 42 75 74 20 66 6f  ry call.  But fo
247f0 72 20 74 68 65 20 73 74 61 74 69 63 20 0a 2a 2a  r the static .**
24800 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68   mutex types, th
24810 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20  e same mutex is 
24820 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72  returned on ever
24830 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a  y call that has.
24840 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65  ** the same type
24850 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   number..**.** T
24860 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
24870 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
24880 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72  deallocates a pr
24890 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f  eviously.** allo
248a0 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75  cated dynamic mu
248b0 74 65 78 2e 20 20 53 51 4c 69 74 65 20 69 73 20  tex.  SQLite is 
248c0 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c  careful to deall
248d0 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64  ocate every.** d
248e0 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61  ynamic mutex tha
248f0 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20  t it allocates. 
24900 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   The dynamic mut
24910 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65  exes must not be
24920 20 69 6e 20 0a 2a 2a 20 75 73 65 20 77 68 65 6e   in .** use when
24930 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f   they are deallo
24940 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70 74 69  cated.  Attempti
24950 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65  ng to deallocate
24960 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74   a static.** mut
24970 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ex results in un
24980 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
24990 2e 20 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20  .  SQLite never 
249a0 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61  deallocates.** a
249b0 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
249c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
249d0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61  _mutex_enter() a
249e0 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
249f0 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20  _try() routines 
24a00 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e  attempt.** to en
24a10 74 65 72 20 61 20 6d 75 74 65 78 2e 20 20 49 66  ter a mutex.  If
24a20 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
24a30 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69  is already withi
24a40 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20  n the mutex,.** 
24a50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
24a60 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b  ter() will block
24a70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
24a80 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65  ex_try() will re
24a90 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42  turn.** SQLITE_B
24aa0 55 53 59 2e 20 20 54 68 65 20 73 71 6c 69 74 65  USY.  The sqlite
24ab0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e  3_mutex_try() in
24ac0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24ad0 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 75 70 6f  SQLITE_OK.** upo
24ae0 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74  n successful ent
24af0 72 79 2e 20 20 4d 75 74 65 78 65 73 20 63 72 65  ry.  Mutexes cre
24b00 61 74 65 64 20 75 73 69 6e 67 20 53 51 4c 49 54  ated using SQLIT
24b10 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
24b20 45 20 63 61 6e 0a 2a 2a 20 62 65 20 65 6e 74 65  E can.** be ente
24b30 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
24b40 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  es by the same t
24b50 68 72 65 61 64 2e 20 20 49 6e 20 73 75 63 68 20  hread.  In such 
24b60 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75  cases the,.** mu
24b70 74 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 74  tex must be exit
24b80 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62  ed an equal numb
24b90 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f  er of times befo
24ba0 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  re another threa
24bb0 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20  d.** can enter. 
24bc0 20 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 72   If the same thr
24bd0 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74  ead tries to ent
24be0 65 72 20 61 6e 79 20 6f 74 68 65 72 20 6b 69 6e  er any other kin
24bf0 64 20 6f 66 20 6d 75 74 65 78 0a 2a 2a 20 6d 6f  d of mutex.** mo
24c00 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68  re than once, th
24c10 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
24c20 64 65 66 69 6e 65 64 2e 20 20 20 53 51 4c 69 74  defined.   SQLit
24c30 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68  e will never exh
24c40 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68  ibit.** such beh
24c50 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e  avior in its own
24c60 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e   use of mutexes.
24c70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24c80 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
24c90 20 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61   routine exits a
24ca0 20 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 0a   mutex that was.
24cb0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e  ** previously en
24cc0 74 65 72 65 64 20 62 79 20 74 68 65 20 73 61 6d  tered by the sam
24cd0 65 20 74 68 72 65 61 64 2e 20 20 54 68 65 20 62  e thread.  The b
24ce0 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
24cf0 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d  defined if the m
24d00 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72  utex is not curr
24d10 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ently entered by
24d20 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20   the.** calling 
24d30 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74  thread or is not
24d40 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63   currently alloc
24d50 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69  ated.  SQLite wi
24d60 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65  ll.** never do e
24d70 69 74 68 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ither..**.** See
24d80 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
24d90 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e  mutex_held()] an
24da0 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d [sqlite3_mutex
24db0 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a  _notheld()]..*/.
24dc0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73  sqlite3_mutex *s
24dd0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
24de0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  oc(int);.void sq
24df0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
24e00 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
24e10 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
24e20 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74  utex_enter(sqlit
24e30 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
24e40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
24e50 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  y(sqlite3_mutex*
24e60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
24e70 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69  mutex_leave(sqli
24e80 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a  te3_mutex*);../*
24e90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
24ea0 74 65 78 20 56 65 72 69 66 63 61 74 69 6f 6e 20  tex Verifcation 
24eb0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 54  Routines.**.** T
24ec0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
24ed0 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69  _held() and sqli
24ee0 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
24ef0 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  d() routines.** 
24f00 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
24f10 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 65   use inside asse
24f20 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e  rt() statements.
24f30 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
24f40 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 20  e.** never uses 
24f50 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 65  these routines e
24f60 78 63 65 70 74 20 69 6e 73 69 64 65 20 61 6e 20  xcept inside an 
24f70 61 73 73 65 72 74 28 29 20 61 6e 64 20 61 70 70  assert() and app
24f80 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  lications.** are
24f90 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c   advised to foll
24fa0 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66 20 74  ow the lead of t
24fb0 68 65 20 63 6f 72 65 2e 20 20 54 68 65 20 63 6f  he core.  The co
24fc0 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69  re only.** provi
24fd0 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  des implementati
24fe0 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f  ons for these ro
24ff0 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69  utines when it i
25000 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
25010 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45  th the SQLITE_DE
25020 42 55 47 20 66 6c 61 67 2e 20 20 45 78 74 65 72  BUG flag.  Exter
25030 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  nal mutex implem
25040 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
25050 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74   only required t
25060 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20  o provide these 
25070 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49  routines if SQLI
25080 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64  TE_DEBUG is.** d
25090 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44  efined and if ND
250a0 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69  EBUG is not defi
250b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
250c0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
250d0 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20   return true if 
250e0 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65  the mutex in the
250f0 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  ir argument.** i
25100 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65  s held or not he
25110 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  ld, respectively
25120 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67  , by the calling
25130 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 54   thread..**.** T
25140 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
25150 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65  n is not require
25160 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65  d to provided ve
25170 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a  rsions of these.
25180 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
25190 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 0a   actually work..
251a0 2a 2a 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d  ** If the implem
251b0 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  entation does no
251c0 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e  t provide workin
251d0 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  g.** versions of
251e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
251f0 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65   it should at le
25200 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62  ast provide stub
25210 73 0a 2a 2a 20 74 68 61 74 20 61 6c 77 61 79 73  s.** that always
25220 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20   return true so 
25230 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f  that one does no
25240 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 0a 2a  t get spurious.*
25250 2a 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c  * assertion fail
25260 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ures..**.** If t
25270 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  he argument to s
25280 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
25290 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  d() is a NULL po
252a0 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68  inter then.** th
252b0 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  e routine should
252c0 20 72 65 74 75 72 6e 20 31 2e 20 20 54 68 69 73   return 1.  This
252d0 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69   seems counter-i
252e0 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a  ntuitive since.*
252f0 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75  * clearly the mu
25300 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65  tex cannot be he
25310 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f  ld if it does no
25320 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68  t exist.  But th
25330 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20  e.** the reason 
25340 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e  the mutex does n
25350 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61  ot exist is beca
25360 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73  use the build is
25370 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75   not.** using mu
25380 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64  texes.  And we d
25390 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61  o not want the a
253a0 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69  ssert() containi
253b0 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74  ng the.** call t
253c0 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
253d0 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20  held() to fail, 
253e0 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  so a non-zero re
253f0 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61  turn is.** the a
25400 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67  ppropriate thing
25410 20 74 6f 20 64 6f 2e 20 20 54 68 65 20 73 71 6c   to do.  The sql
25420 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
25430 6c 64 28 29 20 0a 2a 2a 20 69 6e 74 65 72 66 61  ld() .** interfa
25440 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72  ce should also r
25450 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76  eturn 1 when giv
25460 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
25470 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
25480 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c  3_mutex_held(sql
25490 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e  ite3_mutex*);.in
254a0 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
254b0 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f  notheld(sqlite3_
254c0 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  mutex*);../*.** 
254d0 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
254e0 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Types.**.** The 
254f0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
25500 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63  lloc()] interfac
25510 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  e takes a single
25520 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69   argument.** whi
25530 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  ch is one of the
25540 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
25550 61 6e 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ants..*/.#define
25560 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
25570 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20 30  ST             0
25580 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25590 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20  MUTEX_RECURSIVE 
255a0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
255b0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
255c0 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32  ATIC_MASTER    2
255d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
255e0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
255f0 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c         3  /* sql
25600 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f  ite3_malloc() */
25610 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25620 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
25630 32 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c  2      4  /* sql
25640 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
25650 6f 72 79 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  ory() */.#define
25660 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
25670 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35  ATIC_PRNG      5
25680 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e    /* sqlite3_ran
25690 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  dom() */.#define
256a0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
256b0 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36  ATIC_LRU       6
256c0 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69    /* lru page li
256d0 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  st */../*.** CAP
256e0 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c  I3REF: Low-Level
256f0 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61   Control Of Data
25700 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  base Files.**.**
25710 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   The [sqlite3_fi
25720 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
25730 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
25740 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74  direct call to t
25750 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72  he.** xFileContr
25760 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68  ol method for th
25770 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
25780 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73  thods] object as
25790 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
257a0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
257b0 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 65  tabase identifie
257c0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
257d0 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 0a 2a  argument.  The.*
257e0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * name of the da
257f0 74 61 62 61 73 65 20 69 73 20 74 68 65 20 6e 61  tabase is the na
25800 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74  me assigned to t
25810 68 65 20 64 61 74 61 62 61 73 65 20 62 79 20 74  he database by t
25820 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c  he.** <a href="l
25830 61 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22  ang_attach.html"
25840 3e 41 54 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20  >ATTACH</a> SQL 
25850 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f 70 65  command that ope
25860 6e 65 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ned the.** datab
25870 61 73 65 2e 20 20 54 6f 20 63 6f 6e 74 72 6f 6c  ase.  To control
25880 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
25890 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65  se file, use the
258a0 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20   name "main".** 
258b0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
258c0 72 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 6e  r.  The third an
258d0 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
258e0 65 72 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74  ers to this rout
258f0 69 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65  ine.** are passe
25900 64 20 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75  d directly throu
25910 67 68 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64  gh to the second
25920 20 61 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d   and third param
25930 65 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20  eters of.** the 
25940 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
25950 68 6f 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  hod.  The return
25960 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46   value of the xF
25970 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65  ileControl.** me
25980 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65  thod becomes the
25990 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
259a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a   this routine..*
259b0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f  *.** If the seco
259c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44  nd parameter (zD
259d0 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20  bName) does not 
259e0 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f  match the name o
259f0 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61  f any.** open da
25a00 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
25a10 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69  n SQLITE_ERROR i
25a20 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 69  s returned.  Thi
25a30 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  s error.** code 
25a40 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65  is not remembere
25a50 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62  d and will not b
25a60 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73  e recalled by [s
25a70 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
25a80 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
25a90 5f 65 72 72 6d 73 67 28 29 5d 2e 20 20 54 68 65  _errmsg()].  The
25aa0 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c   underlying xFil
25ab0 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
25ac0 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65  might.** also re
25ad0 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f  turn SQLITE_ERRO
25ae0 52 2e 20 20 54 68 65 72 65 20 69 73 20 6e 6f 20  R.  There is no 
25af0 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69  way to distingui
25b00 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e  sh between.** an
25b10 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61   incorrect zDbNa
25b20 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45  me and an SQLITE
25b30 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72  _ERROR return fr
25b40 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  om the underlyin
25b50 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f  g.** xFileContro
25b60 6c 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20  l method..**.** 
25b70 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
25b80 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
25b90 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  E].*/.int sqlite
25ba0 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73  3_file_control(s
25bb0 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
25bc0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e  har *zDbName, in
25bd0 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t op, void*);../
25be0 2a 0a 2a 2a 20 55 6e 64 6f 20 74 68 65 20 68 61  *.** Undo the ha
25bf0 63 6b 20 74 68 61 74 20 63 6f 6e 76 65 72 74 73  ck that converts
25c00 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
25c10 74 79 70 65 73 20 74 6f 20 69 6e 74 65 67 65 72  types to integer
25c20 20 66 6f 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f   for.** builds o
25c30 6e 20 70 72 6f 63 65 73 73 6f 72 73 20 77 69 74  n processors wit
25c40 68 6f 75 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f  hout floating po
25c50 69 6e 74 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a  int support..*/.
25c60 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
25c70 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
25c80 54 0a 23 20 75 6e 64 65 66 20 64 6f 75 62 6c 65  T.# undef double
25c90 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
25ca0 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f  __cplusplus.}  /
25cb0 2a 20 45 6e 64 20 6f 66 20 74 68 65 20 27 65 78  * End of the 'ex
25cc0 74 65 72 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20  tern "C"' block 
25cd0 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66  */.#endif.#endif
25ce0 0a                                               .