/ Hex Artifact Content
Login

Artifact 2d45cd3fc1b6677d06c8e547bbe1b9a040a7f677:


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 34 33 20 32 30 30 37 2f  in,v 1.243 2007/
05f0: 30 38 2f 32 37 20 31 37 3a 32 37 3a 34 39 20 64  08/27 17:27:49 d
0600: 61 6e 69 65 6c 6b 31 39 37 37 20 45 78 70 20 24  anielk1977 Exp $
0610: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
0620: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
0630: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0640: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0650: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0660: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0670: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0680: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0690: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
06a0: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
06b0: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
06c0: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
06d0: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06e0: 2a 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69  ** Add the abili
06f0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27  ty to override '
0700: 65 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64  extern'.*/.#ifnd
0710: 65 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  ef SQLITE_EXTERN
0720: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
0730: 5f 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23  _EXTERN extern.#
0740: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  endif../*.** Mak
0750: 65 20 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  e sure these sym
0760: 62 6f 6c 73 20 77 68 65 72 65 20 6e 6f 74 20 64  bols where not d
0770: 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70  efined by some p
0780: 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 0a 2a  revious header.*
0790: 2a 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  * file..*/.#ifde
07a0: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
07b0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
07c0: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
07d0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
07e0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
07f0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0800: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0810: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0820: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0830: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0840: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  umbers.**.** The
0850: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
0860: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69  SQLite library i
0870: 73 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  s contained in t
0880: 68 65 20 73 71 6c 69 74 65 33 2e 68 0a 2a 2a 20  he sqlite3.h.** 
0890: 68 65 61 64 65 72 20 66 69 6c 65 20 69 6e 20 61  header file in a
08a0: 20 23 64 65 66 69 6e 65 20 6e 61 6d 65 64 20 53   #define named S
08b0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 2e 20 20  QLITE_VERSION.  
08c0: 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  The SQLITE_VERSI
08d0: 4f 4e 0a 2a 2a 20 6d 61 63 72 6f 20 72 65 73 6f  ON.** macro reso
08e0: 6c 76 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67  lves to a string
08f0: 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a   constant..**.**
0900: 20 54 68 65 20 66 6f 72 6d 61 74 20 6f 66 20 74   The format of t
0910: 68 65 20 76 65 72 73 69 6f 6e 20 73 74 72 69 6e  he version strin
0920: 67 20 69 73 20 22 58 2e 59 2e 5a 22 2c 20 77 68  g is "X.Y.Z", wh
0930: 65 72 65 0a 2a 2a 20 58 20 69 73 20 74 68 65 20  ere.** X is the 
0940: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75  major version nu
0950: 6d 62 65 72 2c 20 59 20 69 73 20 74 68 65 20 6d  mber, Y is the m
0960: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0970: 62 65 72 20 61 6e 64 20 5a 0a 2a 2a 20 69 73 20  ber and Z.** is 
0980: 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62  the release numb
0990: 65 72 2e 20 20 54 68 65 20 58 2e 59 2e 5a 20 6d  er.  The X.Y.Z m
09a0: 69 67 68 74 20 62 65 20 66 6f 6c 6c 6f 77 65 64  ight be followed
09b0: 20 62 79 20 22 61 6c 70 68 61 22 20 6f 72 20 22   by "alpha" or "
09c0: 62 65 74 61 22 2e 0a 2a 2a 20 46 6f 72 20 65 78  beta"..** For ex
09d0: 61 6d 70 6c 65 20 22 33 2e 31 2e 31 62 65 74 61  ample "3.1.1beta
09e0: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 58 20 76  "..**.** The X v
09f0: 61 6c 75 65 20 69 73 20 61 6c 77 61 79 73 20 33  alue is always 3
0a00: 20 69 6e 20 53 51 4c 69 74 65 2e 20 20 54 68 65   in SQLite.  The
0a10: 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68   X value only ch
0a20: 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20 62 61  anges when.** ba
0a30: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
0a40: 69 6c 69 74 79 20 69 73 20 62 72 6f 6b 65 6e 20  ility is broken 
0a50: 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 74 6f  and we intend to
0a60: 20 6e 65 76 65 72 20 62 72 65 61 6b 0a 2a 2a 20   never break.** 
0a70: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0a80: 69 62 69 6c 69 74 79 2e 20 20 54 68 65 20 59 20  ibility.  The Y 
0a90: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0aa0: 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65  es when.** there
0ab0: 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 75   are major featu
0ac0: 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20  re enhancements 
0ad0: 74 68 61 74 20 61 72 65 20 66 6f 72 77 61 72 64  that are forward
0ae0: 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20  s compatible.** 
0af0: 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 64  but not backward
0b00: 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 20 20 54  s compatible.  T
0b10: 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20 69 6e  he Z value is in
0b20: 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a  cremented with.*
0b30: 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65 20 62  * each release b
0b40: 75 74 20 72 65 73 65 74 73 20 62 61 63 6b 20 74  ut resets back t
0b50: 6f 20 30 20 77 68 65 6e 20 59 20 69 73 20 69 6e  o 0 when Y is in
0b60: 63 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  cremented..**.**
0b70: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53   The SQLITE_VERS
0b80: 49 4f 4e 5f 4e 55 4d 42 45 52 20 69 73 20 61 6e  ION_NUMBER is an
0b90: 20 69 6e 74 65 67 65 72 20 77 69 74 68 20 74 68   integer with th
0ba0: 65 20 76 61 6c 75 65 20 0a 2a 2a 20 28 58 2a 31  e value .** (X*1
0bb0: 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20  000000 + Y*1000 
0bc0: 2b 20 5a 29 2e 20 46 6f 72 20 65 78 61 6d 70 6c  + Z). For exampl
0bd0: 65 2c 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 22  e, for version "
0be0: 33 2e 31 2e 31 62 65 74 61 22 2c 20 0a 2a 2a 20  3.1.1beta", .** 
0bf0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0c00: 55 4d 42 45 52 20 69 73 20 73 65 74 20 74 6f 20  UMBER is set to 
0c10: 33 30 30 31 30 30 31 2e 20 54 6f 20 64 65 74 65  3001001. To dete
0c20: 63 74 20 69 66 20 74 68 65 79 20 61 72 65 20 75  ct if they are u
0c30: 73 69 6e 67 20 0a 2a 2a 20 76 65 72 73 69 6f 6e  sing .** version
0c40: 20 33 2e 31 2e 31 20 6f 72 20 67 72 65 61 74 65   3.1.1 or greate
0c50: 72 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  r at compile tim
0c60: 65 2c 20 70 72 6f 67 72 61 6d 73 20 6d 61 79 20  e, programs may 
0c70: 75 73 65 20 74 68 65 20 74 65 73 74 20 0a 2a 2a  use the test .**
0c80: 20 28 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   (SQLITE_VERSION
0c90: 5f 4e 55 4d 42 45 52 3e 3d 33 30 30 31 30 30 31  _NUMBER>=3001001
0ca0: 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
0cb0: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
0cc0: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
0cd0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
0ce0: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2f 0a  n_number()]..*/.
0cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0d00: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 20 22  ERSION         "
0d10: 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e  --VERS--".#defin
0d20: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0d30: 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f  _NUMBER --VERSIO
0d40: 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a  N-NUMBER--../*.*
0d50: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
0d60: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
0d70: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a  sion Numbers.**.
0d80: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
0d90: 73 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20  s return values 
0da0: 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 74 68  equivalent to th
0db0: 65 20 68 65 61 64 65 72 20 63 6f 6e 73 74 61 6e  e header constan
0dc0: 74 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ts.** [SQLITE_VE
0dd0: 52 53 49 4f 4e 5d 20 61 6e 64 20 5b 53 51 4c 49  RSION] and [SQLI
0de0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0df0: 52 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  R].  The values 
0e00: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74  returned.** by t
0e10: 68 69 73 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  his routines sho
0e20: 75 6c 64 20 6f 6e 6c 79 20 62 65 20 64 69 66 66  uld only be diff
0e30: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 68  erent from the h
0e40: 65 61 64 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  eader values.** 
0e50: 69 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65 20 79  if you compile y
0e60: 6f 75 72 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  our program usin
0e70: 67 20 61 6e 20 73 71 6c 69 74 65 33 2e 68 20 68  g an sqlite3.h h
0e80: 65 61 64 65 72 20 66 72 6f 6d 20 61 0a 2a 2a 20  eader from a.** 
0e90: 64 69 66 66 65 72 65 6e 74 20 76 65 72 73 69 6f  different versio
0ea0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
0eb0: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   the version of 
0ec0: 74 68 65 20 6c 69 62 72 61 72 79 20 79 6f 75 0a  the library you.
0ed0: 2a 2a 20 6c 69 6e 6b 20 61 67 61 69 6e 73 74 2e  ** link against.
0ee0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
0ef0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
0f00: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
0f10: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
0f20: 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
0f30: 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67  _VERSION] string
0f40: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
0f50: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
0f60: 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20  tion returns.** 
0f70: 61 20 70 6f 69 6e 65 72 20 74 6f 20 74 68 65 20  a poiner to the 
0f80: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
0f90: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
0fa0: 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
0fb0: 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20  .** is provided 
0fc0: 66 6f 72 20 44 4c 4c 20 75 73 65 72 73 20 77 68  for DLL users wh
0fd0: 6f 20 63 61 6e 20 6f 6e 6c 79 20 61 63 63 65 73  o can only acces
0fe0: 73 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  s functions and 
0ff0: 6e 6f 74 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73  not.** constants
1000: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e   within the DLL.
1010: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
1020: 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c  N const char sql
1030: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a  ite3_version[];.
1040: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1050: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76  te3_libversion(v
1060: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
1070: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
1080: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ber(void);../*.*
1090: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
10a0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
10b0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 45 61 63  Handle.**.** Eac
10c0: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
10d0: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
10e0: 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65 72  ented by pointer
10f0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
1100: 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75 65  of the.** opaque
1110: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
1120: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
1130: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
1140: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
1150: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
1160: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
1170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1190: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
11a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
11b0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
11c0: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 0a  ts constructors.
11d0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
11e0: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73 20  close()] is its 
11f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
1200: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
1210: 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
1220: 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74 65  (such as [sqlite
1230: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1240: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1250: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
1260: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
1270: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
1280: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
1290: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
12a0: 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  s on this.** obj
12b0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
12c0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
12d0: 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  qlite3;.../*.** 
12e0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74  CAPI3REF: 64-Bit
12f0: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a   Integer Types.*
1300: 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f 6d 70 69 6c  *.** Some compil
1310: 65 72 73 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  ers do not suppo
1320: 72 74 20 74 68 65 20 22 6c 6f 6e 67 20 6c 6f 6e  rt the "long lon
1330: 67 22 20 64 61 74 61 74 79 70 65 2e 20 20 53 6f  g" datatype.  So
1340: 20 77 65 20 68 61 76 65 0a 2a 2a 20 74 6f 20 64   we have.** to d
1350: 6f 20 63 6f 6d 70 69 6c 65 72 2d 73 70 65 63 69  o compiler-speci
1360: 66 69 63 20 74 79 70 65 64 65 66 73 20 66 6f 72  fic typedefs for
1370: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
1380: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
1390: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  gers..**.** Many
13a0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
13b0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 71 75  e functions requ
13c0: 69 72 65 20 61 20 36 34 2d 62 69 74 20 69 6e 74  ire a 64-bit int
13d0: 65 67 65 72 20 61 72 67 75 6d 65 6e 74 73 2e 0a  eger arguments..
13e0: 2a 2a 20 54 68 6f 73 65 20 69 6e 74 65 72 66 61  ** Those interfa
13f0: 63 65 73 20 61 72 65 20 64 65 63 6c 61 72 65 64  ces are declared
1400: 20 75 73 69 6e 67 20 74 68 69 73 20 74 79 70 65   using this type
1410: 64 65 66 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  def..*/.#ifdef S
1420: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
1430: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
1440: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
1450: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
1460: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
1470: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
1480: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
1490: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
14a0: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
14b0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
14c0: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
14d0: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
14e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
14f0: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
1500: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
1510: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
1520: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
1530: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
1540: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
1550: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
1560: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
1570: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
1580: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
1590: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
15a0: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
15b0: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
15c0: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
15d0: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
15e0: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
15f0: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
1600: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
1610: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
1620: 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65 66  -point.*/.#ifdef
1630: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
1640: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
1650: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
1660: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
1670: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1680: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
1690: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
16a0: 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 68 69 73 20  **.** Call this 
16b0: 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
16c0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
16d0: 75 63 74 75 72 65 20 74 68 61 74 20 77 61 73 20  ucture that was 
16e0: 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65  previously.** re
16f0: 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
1700: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1710: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1720: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
1730: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20  _open_v2()] and 
1740: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
1750: 67 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  g database will 
1760: 62 79 0a 2a 2a 20 63 6c 6f 73 65 64 2e 0a 2a 2a  by.** closed..**
1770: 0a 2a 2a 20 41 6c 6c 20 53 51 4c 20 73 74 61 74  .** All SQL stat
1780: 65 6d 65 6e 74 73 20 70 72 65 70 61 72 65 64 20  ements prepared 
1790: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
17a0: 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
17b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
17c0: 61 72 65 31 36 5f 76 32 28 29 5d 20 6d 75 73 74  are16_v2()] must
17d0: 20 62 65 20 64 65 73 74 72 6f 79 65 64 20 75 73   be destroyed us
17e0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
17f0: 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 62 65 66 6f  alize()].** befo
1800: 72 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  re this routine 
1810: 69 73 20 63 61 6c 6c 65 64 2e 20 4f 74 68 65 72  is called. Other
1820: 77 69 73 65 2c 20 53 51 4c 49 54 45 5f 42 55 53  wise, SQLITE_BUS
1830: 59 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  Y is returned an
1840: 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  d the.** databas
1850: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 72 65 6d  e connection rem
1860: 61 69 6e 73 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a 2a  ains open..**.**
1870: 20 50 61 73 73 69 6e 67 20 74 68 69 73 20 72 6f   Passing this ro
1880: 75 74 69 6e 65 20 61 20 64 61 74 61 62 61 73 65  utine a database
1890: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
18a0: 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
18b0: 6e 0a 2a 2a 20 63 6c 6f 73 65 64 20 72 65 73 75  n.** closed resu
18c0: 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
18d0: 20 62 65 68 61 76 69 6f 72 2e 20 20 49 66 20 6f   behavior.  If o
18e0: 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  ther interfaces 
18f0: 74 68 61 74 0a 2a 2a 20 72 65 66 65 72 65 6e 63  that.** referenc
1900: 65 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  e the same datab
1910: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  ase connection a
1920: 72 65 20 70 65 6e 64 69 6e 67 20 28 65 69 74 68  re pending (eith
1930: 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 73 61 6d  er in the.** sam
1940: 65 20 74 68 72 65 61 64 20 6f 72 20 69 6e 20 64  e thread or in d
1950: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
1960: 29 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74  ) when this rout
1970: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 0a 2a  ine is called,.*
1980: 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1990: 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
19a0: 20 61 6e 64 20 69 73 20 61 6c 6d 6f 73 74 20 63   and is almost c
19b0: 65 72 74 61 69 6e 6c 79 20 75 6e 64 65 73 69 72  ertainly undesir
19c0: 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  able..*/.int sql
19d0: 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74  ite3_close(sqlit
19e0: 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  e3 *);../*.** Th
19f0: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
1a00: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
1a10: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
1a20: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
1a30: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
1a40: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
1a50: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
1a60: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
1a70: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
1a80: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
1a90: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
1aa0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
1ab0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
1ac0: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
1ad0: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
1ae0: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
1af0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1b00: 69 73 20 75 73 65 64 20 74 6f 20 64 6f 20 61 20  is used to do a 
1b10: 6f 6e 65 2d 74 69 6d 65 20 65 76 61 6c 75 61 74  one-time evaluat
1b20: 61 74 69 6f 6e 20 6f 66 20 7a 65 72 6f 0a 2a 2a  ation of zero.**
1b30: 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 61   or more SQL sta
1b40: 74 65 6d 65 6e 74 73 2e 20 20 55 54 46 2d 38 20  tements.  UTF-8 
1b50: 74 65 78 74 20 6f 66 20 74 68 65 20 53 51 4c 20  text of the SQL 
1b60: 73 74 61 74 65 6d 65 6e 74 73 20 74 6f 0a 2a 2a  statements to.**
1b70: 20 62 65 20 65 76 61 6c 75 74 65 64 20 69 73 20   be evaluted is 
1b80: 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
1b90: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1ba0: 72 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65 6e  r.  The statemen
1bb0: 74 73 0a 2a 2a 20 61 72 65 20 70 72 65 70 61 72  ts.** are prepar
1bc0: 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 73  ed one by one us
1bd0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1be0: 70 61 72 65 28 29 5d 2c 20 65 76 61 6c 75 61 74  pare()], evaluat
1bf0: 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
1c00: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 74 68  ite3_step()], th
1c10: 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  en destroyed usi
1c20: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
1c30: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  lize()]..**.** I
1c40: 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
1c50: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1c60: 6e 74 73 20 61 72 65 20 71 75 65 72 69 65 73 2c  nts are queries,
1c70: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 61 6c   then.** the cal
1c80: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
1c90: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1ca0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
1cb0: 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65  .** invoked once
1cc0: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66   for each row of
1cd0: 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75 6c   the query resul
1ce0: 74 2e 20 20 54 68 69 73 20 63 61 6c 6c 62 61 63  t.  This callbac
1cf0: 6b 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 72 6d  k.** should norm
1d00: 61 6c 6c 79 20 72 65 74 75 72 6e 20 30 2e 20 20  ally return 0.  
1d10: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1d20: 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
1d30: 72 6f 0a 2a 2a 20 76 61 6c 75 65 20 74 68 65 6e  ro.** value then
1d40: 20 74 68 65 20 71 75 65 72 79 20 69 73 20 61 62   the query is ab
1d50: 6f 72 74 65 64 2c 20 61 6c 6c 20 73 75 62 73 65  orted, all subse
1d60: 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d  quent SQL statem
1d70: 65 6e 74 73 0a 2a 2a 20 61 72 65 20 73 6b 69 70  ents.** are skip
1d80: 70 65 64 20 61 6e 64 20 74 68 65 20 73 71 6c 69  ped and the sqli
1d90: 74 65 33 5f 65 78 65 63 28 29 20 66 75 6e 63 74  te3_exec() funct
1da0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1db0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 2e 0a 2a 2a  SQLITE_ABORT..**
1dc0: 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61  .** The 4th para
1dd0: 6d 65 74 65 72 20 74 6f 20 74 68 69 73 20 69 6e  meter to this in
1de0: 74 65 72 66 61 63 65 20 69 73 20 61 6e 20 61 72  terface is an ar
1df0: 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 20  bitrary pointer 
1e00: 74 68 61 74 20 69 73 0a 2a 2a 20 70 61 73 73 65  that is.** passe
1e10: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
1e20: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e30: 6f 6e 20 61 73 20 69 74 73 20 66 69 72 73 74 20  on as its first 
1e40: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1e50: 20 54 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   The 2nd paramet
1e60: 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1e70: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
1e80: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1e90: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 71  columns in the q
1ea0: 75 65 72 79 20 72 65 73 75 6c 74 2e 20 20 54 68  uery result.  Th
1eb0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
1ec0: 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  to the callback.
1ed0: 2a 2a 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ** is an array o
1ee0: 66 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e  f strings holdin
1ef0: 67 20 74 68 65 20 76 61 6c 75 65 73 20 66 6f 72  g the values for
1f00: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   each column.** 
1f10: 61 73 20 65 78 74 72 61 63 74 65 64 20 75 73 69  as extracted usi
1f20: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ng [sqlite3_colu
1f30: 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 20 54  mn_text()]..** T
1f40: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
1f50: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1f60: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
1f70: 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 62 74 61 69  strings.** obtai
1f80: 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ned using [sqlit
1f90: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1fa0: 5d 20 61 6e 64 20 68 6f 6c 64 69 6e 67 0a 2a 2a  ] and holding.**
1fb0: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 65 61   the names of ea
1fc0: 63 68 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  ch column..**.**
1fd0: 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
1fe0: 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 4e 55  nction may be NU
1ff0: 4c 4c 2c 20 65 76 65 6e 20 66 6f 72 20 71 75 65  LL, even for que
2000: 72 69 65 73 2e 20 20 41 20 4e 55 4c 4c 0a 2a 2a  ries.  A NULL.**
2010: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
2020: 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 74 20 6a   an error.  It j
2030: 75 73 74 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  ust means that n
2040: 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 77 69  o callback.** wi
2050: 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ll be invoked..*
2060: 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72  *.** If an error
2070: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70 61   occurs while pa
2080: 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74  rsing or evaluat
2090: 69 6e 67 20 74 68 65 20 53 51 4c 20 28 62 75 74  ing the SQL (but
20a0: 0a 2a 2a 20 6e 6f 74 20 77 68 69 6c 65 20 65 78  .** not while ex
20b0: 65 63 75 74 69 6e 67 20 74 68 65 20 63 61 6c 6c  ecuting the call
20c0: 62 61 63 6b 29 20 74 68 65 6e 20 61 6e 20 61 70  back) then an ap
20d0: 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 0a  propriate error.
20e0: 2a 2a 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  ** message is wr
20f0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
2100: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2110: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2120: 29 5d 20 61 6e 64 0a 2a 2a 20 2a 65 72 72 6d 73  )] and.** *errms
2130: 67 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  g is made to poi
2140: 6e 74 20 74 6f 20 74 68 61 74 20 6d 65 73 73 61  nt to that messa
2150: 67 65 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67  ge.  The calling
2160: 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 73 20   function.** is 
2170: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
2180: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
2190: 72 79 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ry that holds th
21a0: 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
21b0: 67 65 2e 20 20 20 55 73 65 20 5b 73 71 6c 69 74  ge.   Use [sqlit
21c0: 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 74  e3_free()] for t
21d0: 68 69 73 2e 20 20 49 66 20 65 72 72 6d 73 67 3d  his.  If errmsg=
21e0: 3d 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 6e  =NULL,.** then n
21f0: 6f 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  o error message 
2200: 69 73 20 65 76 65 72 20 77 72 69 74 74 65 6e 2e  is ever written.
2210: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  .**.** The retur
2220: 6e 20 76 61 6c 75 65 20 69 73 20 69 73 20 53 51  n value is is SQ
2230: 4c 49 54 45 5f 4f 4b 20 69 66 20 74 68 65 72 65  LITE_OK if there
2240: 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 20 61   are no errors a
2250: 6e 64 0a 2a 2a 20 73 6f 6d 65 20 6f 74 68 65 72  nd.** some other
2260: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
2270: 74 75 72 6e 20 63 6f 64 65 5d 20 69 66 20 74 68  turn code] if th
2280: 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  ere is an error.
2290: 20 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63    .** The partic
22a0: 75 6c 61 72 20 72 65 74 75 72 6e 20 76 61 6c 75  ular return valu
22b0: 65 20 64 65 70 65 6e 64 73 20 6f 6e 20 74 68 65  e depends on the
22c0: 20 74 79 70 65 20 6f 66 20 65 72 72 6f 72 2e 20   type of error. 
22d0: 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  .**.*/.int sqlit
22e0: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
22f0: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
2300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2310: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
2320: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
2330: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
2340: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2350: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
2360: 20 74 6f 20 62 65 20 65 76 61 6c 75 74 65 64 20   to be evaluted 
2370: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
2380: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
2390: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
23a0: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
23b0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
23c0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
23d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23e0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
23f0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
2400: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
2410: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
2420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2430: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
2440: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
2450: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2460: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
2470: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
2480: 54 45 5f 4f 4b 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  TE_OK.**.** Many
2490: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
24a0: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
24b0: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
24c0: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
24d0: 77 6e 0a 2a 2a 20 61 62 6f 76 65 20 69 6e 20 6f  wn.** above in o
24e0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
24f0: 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  s success or fai
2500: 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lure..**.** The 
2510: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 62 6f  result codes abo
2520: 76 65 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ve are the only 
2530: 6f 6e 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  ones returned by
2540: 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 0a 2a   SQLite in its.*
2550: 2a 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  * default config
2560: 75 72 61 74 69 6f 6e 2e 20 20 48 6f 77 65 76 65  uration.  Howeve
2570: 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  r, the [sqlite3_
2580: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
2590: 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 41 50 49 20  codes()].** API 
25a0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73  can be used to s
25b0: 65 74 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  et a database co
25c0: 6e 6e 65 63 74 6f 69 6e 20 74 6f 20 72 65 74 75  nnectoin to retu
25d0: 72 6e 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  rn more detailed
25e0: 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 64 65 73  .** result codes
25f0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2600: 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  : [SQLITE_IOERR_
2610: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
2620: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2a  result codes].**
2630: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2640: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
2650: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
2660: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
2670: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
2680: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
2690: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
26a0: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
26b0: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
26c0: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
26d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
26e0: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
26f0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 49 6e 74 65  * NOT USED. Inte
2700: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
2710: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
2720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
2730: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
2740: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
2750: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
2760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
2770: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
2780: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
2790: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
27a0: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
27b0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
27c0: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
27d0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
27e0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
27f0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
2800: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
2810: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
2820: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
2830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2840: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
2850: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
2860: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
2870: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
2880: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
2890: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
28a0: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
28b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
28c0: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
28d0: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
28e0: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
28f0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
2900: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ()*/.#define SQL
2910: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
2920: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
2930: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
2940: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
2950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
2960: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
2970: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
2980: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
2990: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
29a0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
29b0: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f  ND    12   /* NO
29c0: 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72  T USED. Table or
29d0: 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e   record not foun
29e0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
29f0: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
2a00: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
2a10: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
2a20: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
2a30: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
2a40: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
2a50: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
2a60: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
2a70: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
2a80: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
2a90: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e  COL    15   /* N
2aa0: 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 73  OT USED. Databas
2ab0: 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20  e lock protocol 
2ac0: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
2ad0: 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20   SQLITE_EMPTY   
2ae0: 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61      16   /* Data
2af0: 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f  base is empty */
2b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b10: 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20  SCHEMA      17  
2b20: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
2b30: 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20   schema changed 
2b40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2b50: 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38  E_TOOBIG      18
2b60: 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20     /* String or 
2b70: 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a  BLOB exceeds siz
2b80: 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69  e limit */.#defi
2b90: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
2ba0: 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62  AINT  19   /* Ab
2bb0: 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 74 72  ort due to contr
2bc0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
2bd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2be0: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
2bf0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
2c00: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
2c10: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
2c20: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
2c30: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
2c40: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
2c50: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
2c60: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
2c70: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
2c80: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
2c90: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
2ca0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
2cb0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
2cc0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
2cd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2ce0: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
2cf0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
2d00: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
2d10: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
2d20: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
2d30: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
2d40: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2d50: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
2d60: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
2d70: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
2d80: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
2d90: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
2da0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
2db0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
2dc0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
2dd0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
2de0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
2df0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
2e00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2e10: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
2e20: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
2e30: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
2e40: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
2e50: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
2e60: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
2e70: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
2e80: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
2e90: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
2ea0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
2eb0: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
2ec0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
2ed0: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a   of 26 integer.*
2ee0: 2a 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 64  * result codes d
2ef0: 65 73 63 72 69 62 65 64 20 61 74 20 72 65 73 75  escribed at resu
2f00: 6c 74 2d 63 6f 64 65 73 2e 20 20 48 6f 77 65 76  lt-codes.  Howev
2f10: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
2f20: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a 2a  as shown that.**
2f30: 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72   many of these r
2f40: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
2f50: 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61 69 6e  too course-grain
2f60: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
2f70: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
2f80: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
2f90: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
2fa0: 73 20 75 73 65 72 73 20 6d 69 67 68 74 20 6c 69  s users might li
2fb0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
2fc0: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
2fd0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
2fe0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
2ff0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
3000: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
3010: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
3020: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
3030: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
3040: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
3050: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
3060: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
3070: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
3080: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65  sult codes are e
3090: 6e 61 62 6c 65 64 20 28 6f 72 20 64 69 73 61 62  nabled (or disab
30a0: 6c 65 64 29 20 66 6f 72 20 0a 2a 2a 20 65 61 63  led) for .** eac
30b0: 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  h database.** co
30c0: 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74  nnection using t
30d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  he [sqlite3_exte
30e0: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
30f0: 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a  s()] API..** .**
3100: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
3110: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
3120: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
3130: 20 6c 69 73 74 65 64 20 61 62 6f 76 65 2e 0a 2a   listed above..*
3140: 2a 20 57 65 20 65 78 70 65 63 74 20 74 68 65 20  * We expect the 
3150: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
3160: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3170: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
3180: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
3190: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
31a0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
31b0: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
31c0: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
31d0: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
31e0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
31f0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
3200: 20 0a 2a 2a 20 54 68 65 20 73 79 6d 62 6f 6c 69   .** The symboli
3210: 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78  c name for an ex
3220: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3230: 64 65 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69  de always contai
3240: 6e 73 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  ns a related.** 
3250: 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  primary result c
3260: 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78 2e  ode as a prefix.
3270: 20 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74    Primary result
3280: 20 63 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20 61   codes contain a
3290: 20 73 69 6e 67 6c 65 0a 2a 2a 20 22 5f 22 20 63   single.** "_" c
32a0: 68 61 72 61 63 74 65 72 2e 20 20 45 78 74 65 6e  haracter.  Exten
32b0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
32c0: 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20   contain two or 
32d0: 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63 74  more "_" charact
32e0: 65 72 73 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d 65  ers..** The nume
32f0: 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  ric value of an 
3300: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
3310: 63 6f 64 65 20 63 61 6e 20 62 65 20 63 6f 6e 76  code can be conv
3320: 65 72 74 65 64 20 74 6f 20 69 74 73 0a 2a 2a 20  erted to its.** 
3330: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72  corresponding pr
3340: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
3350: 65 20 62 79 20 6d 61 73 6b 69 6e 67 20 6f 66 66  e by masking off
3360: 20 74 68 65 20 6c 6f 77 65 72 20 38 20 62 79 74   the lower 8 byt
3370: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  es..**.** The SQ
3380: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63  LITE_OK result c
3390: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  ode will never b
33a0: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20  e extended.  It 
33b0: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62  will always.** b
33c0: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a  e exactly zero..
33d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
33e0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20  E_IOERR_READ    
33f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3400: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
3410: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3420: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
3430: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3440: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
3450: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
3460: 49 54 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  ITE         (SQL
3470: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
3480: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3490: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
34a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
34b0: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OERR | (4<<8)).#
34c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
34d0: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20  ERR_DIR_FSYNC   
34e0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
34f0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
3500: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
3510: 52 55 4e 43 41 54 45 20 20 20 20 20 20 28 53 51  RUNCATE      (SQ
3520: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
3530: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3540: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
3550: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
3560: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
3570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3580: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
3590: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
35a0: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
35b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
35c0: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53  RDLOCK        (S
35d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
35e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
35f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
3600: 45 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  E        (SQLITE
3610: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
3620: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3630: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
3640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3650: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 0a 2f  RR | (11<<8))../
3660: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
3670: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
3680: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
3690: 0a 2a 2a 20 43 6f 6d 62 69 6e 61 74 69 6f 6e 20  .** Combination 
36a0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
36b0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
36c0: 75 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 74  used as the.** t
36d0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
36e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
36f0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
3700: 63 65 20 61 6e 64 0a 2a 2a 20 61 73 20 66 6f 75  ce and.** as fou
3710: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
3720: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
3730: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
3740: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
3750: 0a 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  .**.*/.#define S
3760: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
3770: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
3780: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
3790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
37a0: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
37b0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
37c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
37d0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
37e0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
37f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
3800: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
3810: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
3820: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
3830: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
3840: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
3850: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
3860: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
3870: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
3880: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
3890: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
38a0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
38b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
38c0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
38d0: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
38e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
38f0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
3900: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
3910: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
3920: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
3930: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
3940: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
3950: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
3960: 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  002000../*.** CA
3970: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
3980: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
3990: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
39a0: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
39b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
39c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
39d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
39e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
39f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
3a00: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a  f the following.
3a10: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
3a20: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
3a30: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
3a40: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
3a50: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
3a60: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
3a70: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
3a80: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
3a90: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
3aa0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
3ab0: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
3ac0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
3ad0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
3ae0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
3af0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
3b00: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
3b10: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
3b20: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
3b30: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
3b40: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
3b50: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
3b60: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
3b70: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
3b80: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
3b90: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
3ba0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
3bb0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
3bc0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
3bd0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
3be0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
3bf0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
3c00: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
3c10: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
3c20: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
3c30: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
3c40: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
3c50: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
3c60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
3c70: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
3c80: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
3c90: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
3ca0: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
3cb0: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
3cc0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
3cd0: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
3ce0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
3cf0: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
3d00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
3d10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
3d20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
3d30: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
3d40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
3d50: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
3d60: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
3d70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
3d80: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
3d90: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
3da0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
3db0: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
3dc0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
3dd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
3de0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
3df0: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
3e00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
3e10: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
3e20: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
3e30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
3e40: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
3e50: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
3e60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
3e70: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
3e80: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
3e90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
3ea0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
3eb0: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
3ec0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
3ed0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
3ee0: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
3ef0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
3f00: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
3f10: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
3f20: 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
3f30: 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 76  lowing integer v
3f40: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
3f50: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
3f60: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
3f70: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
3f80: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
3f90: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
3fa0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
3fb0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
3fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
3fd0: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
3fe0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
3ff0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
4000: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
4010: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
4020: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
4030: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
4040: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
4050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4060: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
4070: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
4080: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
4090: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a  tion Type Flags.
40a0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
40b0: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
40c0: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
40d0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
40e0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
40f0: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
4100: 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66  ination of the f
4110: 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
4120: 20 76 61 6c 75 65 73 20 61 73 0a 2a 2a 20 74 68   values as.** th
4130: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
4140: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
4150: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
4160: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
4170: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
4180: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
4190: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
41a0: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
41b0: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
41c0: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
41d0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
41e0: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 20 54  t be flushed.  T
41f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 42  he SQLITE_SYNC_B
4200: 41 52 52 49 45 52 20 66 6c 61 67 0a 2a 2a 20 6d  ARRIER flag.** m
4210: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 6e 6f  eans that the no
4220: 74 68 69 6e 67 20 61 63 74 75 61 6c 6c 79 20 6e  thing actually n
4230: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 68  eeds to be synch
4240: 65 64 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ed to mass stora
4250: 67 65 2c 0a 2a 2a 20 62 75 74 20 61 6c 6c 20 77  ge,.** but all w
4260: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
4270: 74 68 61 74 20 6f 63 63 75 72 20 62 65 66 6f 72  that occur befor
4280: 65 20 74 68 65 20 62 61 72 72 69 65 72 20 6d 75  e the barrier mu
4290: 73 74 20 63 6f 6d 70 6c 65 74 65 0a 2a 2a 20 62  st complete.** b
42a0: 65 66 6f 72 65 20 61 6e 79 20 77 72 69 74 65 20  efore any write 
42b0: 6f 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20  operations that 
42c0: 6f 63 63 75 72 20 61 66 74 65 72 20 74 68 65 20  occur after the 
42d0: 62 61 72 72 69 65 72 20 62 65 67 69 6e 2e 0a 2a  barrier begin..*
42e0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
42f0: 43 5f 4e 4f 52 4d 41 4c 20 6d 65 61 6e 73 20 74  C_NORMAL means t
4300: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
4310: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
4320: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
4330: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61  NC_FULL flag mea
4340: 6e 73 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ns to use Mac OS
4350: 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e  -X style fullsyn
4360: 63 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20  c.** instead of 
4370: 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66  fsync()..*/.#def
4380: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
4390: 42 41 52 52 49 45 52 20 20 20 20 20 20 20 30 78  BARRIER       0x
43a0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
43b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
43c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
43d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
43e0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
43f0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
4400: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
4410: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
4420: 30 31 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  010.../*.** CAPI
4430: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
4440: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
4450: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
4460: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
4470: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
4480: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
4490: 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e OS.** interfac
44a0: 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69  e layer.  Indivi
44b0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
44c0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
44d0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
44e0: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
44f0: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
4500: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
4510: 69 65 6c 64 73 0a 2a 2a 20 6f 66 20 74 68 65 69  ields.** of thei
4520: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
4530: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
4540: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
4550: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
4560: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
4570: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
4580: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
4590: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
45a0: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
45b0: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
45c0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
45d0: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
45e0: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
45f0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
4600: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
4610: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
4620: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
4630: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
4640: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
4650: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
4660: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
4670: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
4680: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
4690: 79 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  y open file in t
46a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
46b0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f   xOpen method co
46c0: 6e 74 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72  ntains a pointer
46d0: 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e   to.** an instan
46e0: 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ce of the follow
46f0: 69 6e 67 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  ing object.  Thi
4700: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
4710: 20 74 68 65 0a 2a 2a 20 6d 65 74 68 6f 64 73 20   the.** methods 
4720: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
4730: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
4740: 6e 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ns against the o
4750: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  pen file..**.** 
4760: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
4770: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
4780: 62 65 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45  be one of SQLITE
4790: 5f 53 59 4e 43 5f 42 41 52 52 49 45 52 2c 0a 2a  _SYNC_BARRIER,.*
47a0: 2a 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  * SQLITE_SYNC_NO
47b0: 52 4d 41 4c 2c 20 53 51 4c 49 54 45 5f 53 59 4e  RMAL, SQLITE_SYN
47c0: 43 5f 46 55 4c 4c 2e 20 20 54 68 65 20 66 69 72  C_FULL.  The fir
47d0: 73 74 20 63 68 6f 69 63 65 20 6d 65 61 6e 73 20  st choice means 
47e0: 74 68 61 74 0a 2a 2a 20 64 61 74 61 20 69 73 20  that.** data is 
47f0: 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20  not necessarily 
4800: 73 79 6e 63 65 64 20 74 6f 20 64 69 73 6b 20 63  synced to disk c
4810: 6f 6d 70 6c 65 74 65 6c 79 2c 20 6f 6e 6c 79 20  ompletely, only 
4820: 74 68 61 74 0a 2a 2a 20 61 6c 6c 20 77 72 69 74  that.** all writ
4830: 65 73 20 74 68 61 74 20 6f 63 63 75 72 20 62 65  es that occur be
4840: 66 6f 72 65 20 74 68 65 20 73 79 6e 63 20 63 6f  fore the sync co
4850: 6d 70 6c 65 74 65 20 62 65 66 6f 72 65 20 61 6e  mplete before an
4860: 79 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 61 74  y.** writes that
4870: 20 6f 63 63 75 72 20 61 66 74 65 72 20 74 68 65   occur after the
4880: 20 73 79 6e 63 2e 20 20 54 68 65 20 73 65 63 6f   sync.  The seco
4890: 6e 64 20 66 6c 61 67 20 69 73 20 74 68 65 0a 2a  nd flag is the.*
48a0: 2a 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  * normal fsync()
48b0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 66 6c 61  .  The third fla
48c0: 67 20 69 73 20 61 20 4f 53 2d 58 20 73 74 79 6c  g is a OS-X styl
48d0: 65 20 66 75 6c 6c 73 79 6e 63 2e 0a 2a 2a 20 54  e fullsync..** T
48e0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
48f0: 41 54 41 20 66 6c 61 67 20 6d 61 79 20 62 65 20  ATA flag may be 
4900: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
4910: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 0a 2a 2a  ate that only.**
4920: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
4930: 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74 20 69 74   file and not it
4940: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
4950: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a   be synced..** .
4960: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
4970: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
4980: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
4990: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 53 51 4c  re one of.** SQL
49a0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 2c 20 53  ITE_LOCK_NONE, S
49b0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 41 44 2c  QLITE_LOCK_READ,
49c0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
49d0: 45 52 56 45 44 2c 0a 2a 2a 20 53 51 4c 49 54 45  ERVED,.** SQLITE
49e0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 2c 20 6f  _LOCK_PENDING, o
49f0: 72 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  r SQLITE_LOCK_EX
4a00: 43 4c 55 53 49 56 45 2e 20 20 78 4c 6f 63 6b 28  CLUSIVE.  xLock(
4a10: 29 0a 2a 2a 20 69 6e 63 72 65 61 73 65 73 20 74  ).** increases t
4a20: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
4a30: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
4a40: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20   lock.  .** The 
4a50: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
4a60: 63 6b 28 29 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b  ck() method look
4a70: 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  s.** to see if a
4a80: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
4a90: 65 63 74 69 6f 6e 2c 20 65 69 74 68 65 72 20 69  ection, either i
4aa0: 6e 20 74 68 69 73 0a 2a 2a 20 70 72 6f 63 65 73  n this.** proces
4ab0: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
4ac0: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
4ad0: 6f 6c 64 69 6e 67 20 61 6e 20 52 45 53 45 52 56  olding an RESERV
4ae0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
4af0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
4b00: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
4b10: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
4b20: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
4b30: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
4b40: 73 65 20 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a  se if not..** .*
4b50: 2a 20 78 42 72 65 61 6b 4c 6f 63 6b 28 29 20 61  * xBreakLock() a
4b60: 74 74 65 6d 70 74 73 20 74 6f 20 62 72 65 61 6b  ttempts to break
4b70: 20 61 20 6c 6f 63 6b 20 68 65 6c 64 20 62 79 20   a lock held by 
4b80: 61 6e 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2e  another process.
4b90: 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 62 65 20  .** This can be 
4ba0: 75 73 65 64 20 74 6f 20 72 65 6d 6f 76 65 20 61  used to remove a
4bb0: 20 73 74 61 6c 65 20 64 6f 74 2d 66 69 6c 65 20   stale dot-file 
4bc0: 6c 6f 63 6b 2c 20 66 6f 72 20 65 78 61 6d 70 6c  lock, for exampl
4bd0: 65 2e 0a 2a 2a 20 49 74 20 72 65 74 75 72 6e 73  e..** It returns
4be0: 20 30 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e   0 on success an
4bf0: 64 20 6e 6f 6e 2d 7a 65 72 6f 20 66 6f 72 20 61  d non-zero for a
4c00: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
4c10: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
4c20: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
4c30: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
4c40: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
4c50: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
4c60: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
4c70: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
4c80: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
4c90: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
4ca0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
4cb0: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
4cc0: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
4cd0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
4ce0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
4cf0: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
4d00: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
4d10: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
4d20: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
4d30: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
4d40: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
4d50: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54  l>.** <li> SQLIT
4d60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 0a 2a  E_IOCAP_ATOMIC.*
4d70: 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f  * <li> SQLITE_IO
4d80: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 0a 2a 2a  CAP_ATOMIC512.**
4d90: 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43   <li> SQLITE_IOC
4da0: 41 50 5f 41 54 4f 4d 49 43 31 4b 0a 2a 2a 20 3c  AP_ATOMIC1K.** <
4db0: 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  li> SQLITE_IOCAP
4dc0: 5f 41 54 4f 4d 49 43 32 4b 0a 2a 2a 20 3c 6c 69  _ATOMIC2K.** <li
4dd0: 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  > SQLITE_IOCAP_A
4de0: 54 4f 4d 49 43 34 4b 0a 2a 2a 20 3c 6c 69 3e 20  TOMIC4K.** <li> 
4df0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4e00: 4d 49 43 38 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51  MIC8K.** <li> SQ
4e10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4e20: 43 31 36 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c  C16K.** <li> SQL
4e30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
4e40: 33 32 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49  32K.** <li> SQLI
4e50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
4e60: 34 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54  4K.** <li> SQLIT
4e70: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
4e80: 45 4e 44 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49  END.** <li> SQLI
4e90: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
4ea0: 49 41 4c 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IAL.** </ul>.**.
4eb0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
4ec0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
4ed0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
4ee0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
4ef0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
4f00: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
4f10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
4f20: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
4f30: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
4f40: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
4f50: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
4f60: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
4f70: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
4f80: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
4f90: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
4fa0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
4fb0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
4fc0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
4fd0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
4fe0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
4ff0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
5000: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
5010: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
5020: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
5030: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
5040: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
5050: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
5060: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
5070: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
5080: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
5090: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
50a0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
50b0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
50c0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
50d0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
50e0: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70  xWrite()..*/.typ
50f0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
5100: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
5110: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5120: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
5130: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
5140: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
5150: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
5160: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
5170: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
5180: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
5190: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
51a0: 6c 69 74 65 5f 69 6e 74 36 34 20 69 4f 66 73 74  lite_int64 iOfst
51b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
51c0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
51d0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
51e0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 5f  nt iAmt, sqlite_
51f0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
5200: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
5210: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
5220: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 69 7a  sqlite_int64 siz
5230: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
5240: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
5250: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
5260: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
5270: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
5280: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 2a 70 53  sqlite_int64 *pS
5290: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
52a0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
52b0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
52c0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
52d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
52e0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
52f0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
5300: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
5310: 74 20 28 2a 78 42 72 65 61 6b 4c 6f 63 6b 29 28  t (*xBreakLock)(
5320: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
5330: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 53 74 61    int (*xLockSta
5340: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
5350: 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65   *);.  int (*xSe
5360: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
5370: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
5380: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
5390: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
53a0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41  3_file*);.  /* A
53b0: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
53c0: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
53d0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
53e0: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
53f0: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
5400: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
5410: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
5420: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
5430: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
5440: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
5450: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
5460: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
5470: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
5480: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
5490: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
54a0: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
54b0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
54c0: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
54d0: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
54e0: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
54f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
5500: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
5510: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
5520: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
5530: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
5540: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
5550: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
5560: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
5570: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5580: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
5590: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
55a0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
55b0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
55c0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
55d0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
55e0: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
55f0: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
5600: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
5610: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
5620: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
5630: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
5640: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
5650: 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 56  m"..**.** The iV
5660: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
5670: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
5680: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 66 6f  may be larger fo
5690: 72 20 66 75 74 75 72 65 0a 2a 2a 20 76 65 72 73  r future.** vers
56a0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
56b0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
56c0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
56d0: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
56e0: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
56f0: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
5700: 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a  increased..**.**
5710: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
5720: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
5730: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
5740: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 0a 2a  d sqlite3_file.*
5750: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
5760: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
5770: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
5780: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
5790: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
57a0: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
57b0: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 76  .** Registered v
57c0: 66 73 20 6d 6f 64 75 6c 65 73 20 61 72 65 20 6b  fs modules are k
57d0: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
57e0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
57f0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
5800: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
5810: 65 33 5f 72 65 67 69 73 74 65 72 5f 76 66 73 28  e3_register_vfs(
5820: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
5830: 65 33 5f 75 6e 72 65 67 69 73 74 65 72 5f 76 66  e3_unregister_vf
5840: 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  s()] interfaces 
5850: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
5860: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
5870: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
5880: 73 71 6c 69 74 65 33 5f 66 69 6e 64 5f 76 66 73  sqlite3_find_vfs
5890: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
58a0: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
58b0: 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  st..**.** The pN
58c0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
58d0: 20 6f 6e 6c 79 20 66 69 65 6c 64 73 20 69 6e 20   only fields in 
58e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
58f0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68  .** structure th
5900: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  at SQLite will e
5910: 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c  ver modify.  SQL
5920: 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63  ite will only ac
5930: 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66  cess.** or modif
5940: 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69  y this field whi
5950: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
5960: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
5970: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
5980: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
5990: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
59a0: 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65  thing within the
59b0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
59c0: 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20  object once the 
59d0: 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20  object has been 
59e0: 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a  registered..**.*
59f0: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
5a00: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
5a10: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
5a20: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
5a30: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
5a40: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
5a50: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51  odules..**.** SQ
5a60: 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e  Lite will guaran
5a70: 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69  tee that the zFi
5a80: 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67 20 70 61  lename string pa
5a90: 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e  ssed to.** xOpen
5aa0: 28 29 20 69 73 20 61 20 66 75 6c 6c 20 70 61 74  () is a full pat
5ab0: 68 6e 61 6d 65 20 61 73 20 67 65 6e 65 72 61 74  hname as generat
5ac0: 65 64 20 62 79 20 78 46 75 6c 6c 50 61 74 68 6e  ed by xFullPathn
5ad0: 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61  ame() and.** tha
5ae0: 74 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  t the string wil
5af0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
5b00: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
5b10: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
5b20: 6c 6c 65 64 2e 20 20 53 6f 20 74 68 65 20 73 71  lled.  So the sq
5b30: 6c 69 74 65 33 5f 66 69 6c 65 20 63 61 6e 20 73  lite3_file can s
5b40: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
5b50: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
5b60: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
5b70: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
5b80: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
5b90: 72 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  reason..**.** Th
5ba0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
5bb0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 73 20 61   to xOpen() is a
5bc0: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6c 61   copy of the fla
5bd0: 67 73 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  gs argument.** t
5be0: 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
5bf0: 32 28 29 2e 20 20 49 66 20 73 71 6c 69 74 65 33  2().  If sqlite3
5c00: 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
5c10: 65 33 5f 6f 70 65 6e 31 36 28 29 0a 2a 2a 20 69  e3_open16().** i
5c20: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
5c30: 67 73 20 69 73 20 53 51 4c 49 54 45 5f 4f 50 45  gs is SQLITE_OPE
5c40: 4e 5f 52 45 41 44 57 52 49 54 45 20 7c 20 53 51  N_READWRITE | SQ
5c50: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5c60: 2e 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20  ..** If xOpen() 
5c70: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
5c80: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
5c90: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
5ca0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 53 51 4c  o.** include SQL
5cb0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
5cc0: 59 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  Y.  Other bits i
5cd0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
5ce0: 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20 0a   be.** set..** .
5cf0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  ** SQLite will a
5d00: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
5d10: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
5d20: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
5d30: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
5d40: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
5d50: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
5d60: 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  .** .** <ul>.** 
5d70: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
5d80: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
5d90: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
5da0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
5db0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
5dc0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
5dd0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
5de0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5df0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
5e00: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
5e10: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
5e20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
5e30: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f  R_JOURNAL].** </
5e40: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ul>.**.** The fi
5e50: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
5e60: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
5e70: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
5e80: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
5e90: 73 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  s the way it dea
5ea0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
5eb0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
5ec0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
5ed0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
5ee0: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
5ef0: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
5f00: 63 6b 2c 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ck, might make.*
5f10: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
5f20: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
5f30: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
5f40: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72   this journal ar
5f50: 65 0a 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f  e.** also a no-o
5f60: 70 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20  p.  Any attempt 
5f70: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
5f80: 6e 61 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  nal return SQLIT
5f90: 45 5f 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74  E_IOERR..** Or t
5fa0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
5fb0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
5fc0: 65 20 74 68 65 20 61 20 64 61 74 61 62 61 73 65  e the a database
5fd0: 20 66 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65   file will.** be
5fe0: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
5ff0: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
6000: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
6010: 20 72 61 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a   random order.**
6020: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
6030: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
6040: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a  cordingly..** .*
6050: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
6060: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
6070: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
6080: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a  gs to the xOpen.
6090: 2a 2a 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a  ** method:.** .*
60a0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
60b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
60c0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
60d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
60e0: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
60f0: 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 5b  ul>.** .** The [
6100: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
6110: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
6120: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
6130: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
6140: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
6150: 6c 6f 73 65 64 2e 20 20 54 68 69 73 20 77 69 6c  losed.  This wil
6160: 6c 20 61 6c 77 61 79 73 20 62 65 20 73 65 74 20  l always be set 
6170: 66 6f 72 20 54 45 4d 50 20 0a 2a 2a 20 64 61 74  for TEMP .** dat
6180: 61 62 61 73 65 73 20 61 6e 64 20 6a 6f 75 72 6e  abases and journ
6190: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
61a0: 6f 75 72 6e 61 6c 73 2e 20 20 54 68 65 20 0a 2a  ournals.  The .*
61b0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  * [SQLITE_OPEN_E
61c0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d  XCLUSIVE] flag m
61d0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
61e0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a  ould be opened.*
61f0: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
6200: 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c  access.  This fl
6210: 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c  ag is set for al
6220: 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a  l files except.*
6230: 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64  * for the main d
6240: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
6250: 20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33   .** The sqlite3
6260: 5f 66 69 6c 65 20 73 74 72 75 63 74 75 72 65 20  _file structure 
6270: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
6280: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ird argument to.
6290: 2a 2a 20 78 4f 70 65 6e 20 69 73 20 61 6c 6c 6f  ** xOpen is allo
62a0: 63 61 74 65 64 20 62 79 20 74 68 65 20 63 61 6c  cated by the cal
62b0: 6c 65 72 2e 20 20 78 4f 70 65 6e 20 6a 75 73 74  ler.  xOpen just
62c0: 20 66 69 6c 6c 73 20 69 74 20 69 6e 2e 20 20 54   fills it in.  T
62d0: 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 20 61 6c 6c  he.** caller all
62e0: 6f 63 61 74 65 73 20 61 20 6d 69 6e 69 6d 75 6d  ocates a minimum
62f0: 20 6f 66 20 73 7a 4f 73 46 69 6c 65 20 62 79 74   of szOsFile byt
6300: 65 73 20 66 6f 72 20 74 68 65 20 73 71 6c 69 74  es for the sqlit
6310: 65 33 5f 66 69 6c 65 0a 2a 2a 20 73 74 72 75 63  e3_file.** struc
6320: 74 75 72 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  ture..** .** The
6330: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
6340: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
6350: 20 62 65 20 30 20 28 74 6f 20 74 65 73 74 20 66   be 0 (to test f
6360: 6f 72 20 74 68 65 0a 2a 2a 20 65 78 69 73 74 61  or the.** exista
6370: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 29 20 6f  nce of a file) o
6380: 72 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  r SQLITE_ACCESS_
6390: 52 45 41 44 57 52 49 54 45 20 74 6f 20 74 65 73  READWRITE to tes
63a0: 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61  t to see.** if a
63b0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
63c0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
63d0: 6f 72 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  or SQLITE_ACCESS
63e0: 5f 52 45 41 44 4f 4e 4c 59 0a 2a 2a 20 74 6f 20  _READONLY.** to 
63f0: 74 65 73 74 20 74 6f 20 73 65 65 20 69 66 20 61  test to see if a
6400: 20 66 69 6c 65 20 69 73 20 72 65 61 64 2d 6f 6e   file is read-on
6410: 6c 79 2e 20 20 54 68 65 20 66 69 6c 65 20 63 61  ly.  The file ca
6420: 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69 72 65 63  n be a .** direc
6430: 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c  tory..** .** SQL
6440: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
6450: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
6460: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
6470: 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f  yte for.** the o
6480: 75 74 70 75 74 20 62 75 66 66 65 72 73 20 66 6f  utput buffers fo
6490: 72 20 78 47 65 74 54 65 6d 70 4e 61 6d 65 20 61  r xGetTempName a
64a0: 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  nd xFullPathname
64b0: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61  ..** .** The xRa
64c0: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
64d0: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  ep(), and xCurre
64e0: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61  ntTime() interfa
64f0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73  ces.** are not s
6500: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
6510: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
6520: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
6530: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
6540: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
6550: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
6560: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
6570: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
6580: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
6590: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
65a0: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
65b0: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
65c0: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
65d0: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
65e0: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
65f0: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
6600: 61 6e 64 6f 6d 6e 65 73 73 20 67 65 6e 65 72 61  andomness genera
6610: 74 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c  ted.  The.** xSl
6620: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
6630: 73 65 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  se the calling t
6640: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
6650: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
6660: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
6670: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
6680: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
6690: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
66a0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
66b0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
66c0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
66d0: 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a  and.** time..*/.
66e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
66f0: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
6700: 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73  e3_vfs;.struct s
6710: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
6720: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
6730: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
6740: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
6750: 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f  ber */.  int szO
6760: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
6770: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
6780: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
6790: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
67a0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
67b0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
67c0: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
67d0: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
67e0: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
67f0: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
6800: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
6810: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
6820: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
6830: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
6840: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
6850: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
6860: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
6870: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
6880: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
6890: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
68a0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
68b0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
68c0: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
68d0: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
68e0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
68f0: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
6900: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
6910: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
6920: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
6930: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
6940: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
6950: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
6960: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
6970: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
6980: 20 28 2a 78 47 65 74 54 65 6d 70 4e 61 6d 65 29   (*xGetTempName)
6990: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
69a0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
69b0: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
69c0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
69d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
69e0: 6d 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  me, char *zOut);
69f0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
6a00: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
6a10: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
6a20: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
6a30: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
6a40: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
6a50: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
6a60: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Msg);.  void *(*
6a70: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
6a80: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
6a90: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
6aa0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
6ab0: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
6ac0: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
6ad0: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
6ae0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
6af0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
6b00: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
6b10: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
6b20: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
6b30: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
6b40: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
6b50: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
6b60: 65 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69  e*);.  /* New fi
6b70: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
6b80: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
6b90: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
6ba0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
6bb0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
6bc0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
6bd0: 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 23  appens. */.};..#
6be0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
6bf0: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
6c00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c10: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
6c20: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6c30: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 4f 4e 4c  E_ACCESS_READONL
6c40: 59 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  Y  2../*.** CAPI
6c50: 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
6c60: 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
6c70: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
6c80: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
6c90: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
6ca0: 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  bles the.** [SQL
6cb0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
6cc0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
6cd0: 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 2e   codes] feature.
6ce0: 0a 2a 2a 20 42 79 20 64 65 66 61 75 6c 74 2c 20  .** By default, 
6cf0: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
6d00: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
6d10: 66 20 6f 6e 6c 79 20 32 36 20 69 6e 74 65 67 65  f only 26 intege
6d20: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  r.** [SQLITE_OK 
6d30: 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e  | result codes].
6d40: 20 20 57 68 65 6e 20 65 78 74 65 6e 64 65 64 20    When extended 
6d50: 72 65 73 75 6c 74 20 63 6f 64 65 73 0a 2a 2a 20  result codes.** 
6d60: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 74  are enabled by t
6d70: 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 65  his routine, the
6d80: 20 72 65 70 65 74 6f 69 72 65 20 6f 66 20 72 65   repetoire of re
6d90: 73 75 6c 74 20 63 6f 64 65 73 20 63 61 6e 20 62  sult codes can b
6da0: 65 0a 2a 2a 20 6d 75 63 68 20 6c 61 72 67 65 72  e.** much larger
6db0: 20 61 6e 64 20 63 61 6e 20 28 68 6f 70 65 66 75   and can (hopefu
6dc0: 6c 6c 79 29 20 70 72 6f 76 69 64 65 20 6d 6f 72  lly) provide mor
6dd0: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
6de0: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
6df0: 74 68 65 20 63 61 75 73 65 20 6f 66 20 61 6e 20  the cause of an 
6e00: 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
6e10: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6e20: 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61   is a boolean va
6e30: 6c 75 65 20 74 68 61 74 20 74 75 72 6e 73 20 65  lue that turns e
6e40: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
6e50: 2a 20 63 6f 64 65 73 20 6f 6e 20 61 6e 64 20 6f  * codes on and o
6e60: 66 66 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65  ff.  Extended re
6e70: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6f  sult codes are o
6e80: 66 66 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ff by default fo
6e90: 72 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  r.** backwards c
6ea0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
6eb0: 68 20 6f 6c 64 65 72 20 76 65 72 73 69 6f 6e 73  h older versions
6ec0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
6ed0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
6ee0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
6ef0: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
6f00: 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
6f10: 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
6f20: 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
6f30: 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
6f40: 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
6f50: 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
6f60: 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
6f70: 20 6b 65 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 74   key.** called t
6f80: 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20  he "rowid". The 
6f90: 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
6fa0: 61 76 61 69 6c 61 62 6c 65 20 61 73 20 61 6e 20  available as an 
6fb0: 75 6e 64 65 63 6c 61 72 65 64 0a 2a 2a 20 63 6f  undeclared.** co
6fc0: 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
6fd0: 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
6fe0: 5f 2e 20 20 49 66 20 74 68 65 20 74 61 62 6c 65  _.  If the table
6ff0: 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
7000: 0a 2a 2a 20 74 79 70 65 20 49 4e 54 45 47 45 52  .** type INTEGER
7010: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65   PRIMARY KEY the
7020: 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
7030: 20 61 6e 6f 74 68 65 72 20 61 6e 20 61 6c 69 61   another an alia
7040: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 72 6f 77  s for the.** row
7050: 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  id..**.** This r
7060: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
7070: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
7080: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
7090: 52 54 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 64  RT into.** the d
70a0: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
70b0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
70c0: 74 69 6f 6e 20 67 69 76 65 6e 20 69 6e 20 74 68  tion given in th
70d0: 65 20 66 69 72 73 74 20 0a 2a 2a 20 61 72 67 75  e first .** argu
70e0: 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 69 6e 73  ment.  If no ins
70f0: 65 72 74 73 20 68 61 76 65 20 65 76 65 72 20 6f  erts have ever o
7100: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 69 73 20  ccurred on this 
7110: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
7120: 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
7130: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
7140: 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63  If an INSERT occ
7150: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
7160: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  gger, then the r
7170: 6f 77 69 64 20 6f 66 20 74 68 65 0a 2a 2a 20 69  owid of the.** i
7180: 6e 73 65 72 74 65 64 20 72 6f 77 20 69 73 20 72  nserted row is r
7190: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
71a0: 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20  routine as long 
71b0: 61 73 20 74 68 65 20 74 72 69 67 67 65 72 0a 2a  as the trigger.*
71c0: 2a 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 42  * is running.  B
71d0: 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
71e0: 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20  ger terminates, 
71f0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
7200: 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  ed.** by this ro
7210: 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
7220: 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20   the last value 
7230: 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20  inserted before 
7240: 74 68 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 66  the.** trigger f
7250: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ired..**.** If a
7260: 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 64 6f  nother thread do
7270: 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72 74 20  es a new insert 
7280: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
7290: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
72a0: 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  ** while this ro
72b0: 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
72c0: 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
72d0: 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
72e0: 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 74 68 65 6e  t rowid,.** then
72f0: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
7300: 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
7310: 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e is undefined..
7320: 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
7330: 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
7340: 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
7350: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
7360: 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
7370: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
7380: 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 54  Modified.**.** T
7390: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
73a0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
73b0: 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
73c0: 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
73d0: 65 64 0a 2a 2a 20 28 6f 72 20 69 6e 73 65 72 74  ed.** (or insert
73e0: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 29 20 62  ed or deleted) b
73f0: 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
7400: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  t SQL statement.
7410: 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 65    Only.** change
7420: 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
7430: 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
7440: 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
7450: 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 54  ATE, or.** DELET
7460: 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  E statement are 
7470: 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
7480: 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
7490: 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
74a0: 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  s are not counte
74b0: 64 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c  d.  Use the [sql
74c0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
74d0: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
74e0: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
74f0: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
7500: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
7510: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
7520: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
7530: 2a 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  * Within the bod
7540: 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 20  y of a trigger, 
7550: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
7560: 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
7570: 63 61 6e 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  can be.** called
7580: 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
7590: 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
75a0: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
75b0: 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
75c0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
75d0: 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
75e0: 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
75f0: 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 74  he body of the t
7600: 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 6c  rigger..**.** Al
7610: 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  l changes are co
7620: 75 6e 74 65 64 2c 20 65 76 65 6e 20 69 66 20 74  unted, even if t
7630: 68 65 79 20 77 65 72 65 20 6c 61 74 65 72 20 75  hey were later u
7640: 6e 64 6f 6e 65 20 62 79 20 61 0a 2a 2a 20 52 4f  ndone by a.** RO
7650: 4c 4c 42 41 43 4b 20 6f 72 20 41 42 4f 52 54 2e  LLBACK or ABORT.
7660: 20 20 45 78 63 65 70 74 2c 20 63 68 61 6e 67 65    Except, change
7670: 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
7680: 68 20 63 72 65 61 74 69 6e 67 20 61 6e 64 0a 2a  h creating and.*
7690: 2a 20 64 72 6f 70 70 69 6e 67 20 74 61 62 6c 65  * dropping table
76a0: 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  s are not counte
76b0: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61  d..**.** If a ca
76c0: 6c 6c 62 61 63 6b 20 69 6e 76 6f 6b 65 73 20 5b  llback invokes [
76d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
76e0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
76f0: 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 2c  ()] recursively,
7700: 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 68 61  .** then the cha
7710: 6e 67 65 73 20 69 6e 20 74 68 65 20 69 6e 6e 65  nges in the inne
7720: 72 2c 20 72 65 63 75 72 73 69 76 65 20 63 61 6c  r, recursive cal
7730: 6c 20 61 72 65 20 63 6f 75 6e 74 65 64 20 74 6f  l are counted to
7740: 67 65 74 68 65 72 0a 2a 2a 20 77 69 74 68 20 74  gether.** with t
7750: 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  he changes in th
7760: 65 20 6f 75 74 65 72 20 63 61 6c 6c 2e 0a 2a 2a  e outer call..**
7770: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
7780: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
7790: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
77a0: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20  able" without a 
77b0: 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20  WHERE clause.** 
77c0: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
77d0: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
77e0: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
77f0: 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e  much faster than
7800: 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67   going.** throug
7810: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
7820: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
7830: 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c  ts from the tabl
7840: 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a  e.)  Because of.
7850: 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61  ** this optimiza
7860: 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65  tion, the change
7870: 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45   count for "DELE
7880: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
7890: 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72  ill be.** zero r
78a0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
78b0: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
78c0: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
78d0: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a  iginally in the.
78e0: 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74  ** table. To get
78f0: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
7900: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
7910: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
7920: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
7930: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
7940: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a  E 1" instead..**
7950: 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
7960: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
7970: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
7980: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7990: 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69  ion.** while thi
79a0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
79b0: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 72 65  ning then the re
79c0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
79d0: 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73  is routine.** is
79e0: 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69   undefined..*/.i
79f0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
7a00: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
7a10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
7a20: 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
7a30: 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 2a  ows Modified.***
7a40: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
7a50: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
7a60: 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
7a70: 20 72 6f 77 73 20 74 68 61 74 20 68 61 76 65 20   rows that have 
7a80: 62 65 65 6e 0a 2a 2a 20 6d 6f 64 69 66 69 65 64  been.** modified
7a90: 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41   by INSERT, UPDA
7aa0: 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
7ab0: 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
7ac0: 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
7ad0: 65 0a 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e  e.** was opened.
7ae0: 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 55   This includes U
7af0: 50 44 41 54 45 2c 20 49 4e 53 45 52 54 20 61 6e  PDATE, INSERT an
7b00: 64 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  d DELETE stateme
7b10: 6e 74 73 20 65 78 65 63 75 74 65 64 0a 2a 2a 20  nts executed.** 
7b20: 61 73 20 70 61 72 74 20 6f 66 20 74 72 69 67 67  as part of trigg
7b30: 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 41 6c 6c  er programs. All
7b40: 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
7b50: 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  nted as soon as 
7b60: 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
7b70: 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
7b80: 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
7b90: 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
7ba0: 74 20 68 61 6e 64 6c 65 20 69 73 0a 2a 2a 20 70  t handle is.** p
7bb0: 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
7bc0: 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
7bd0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 73 65 28  qlite3_finalise(
7be0: 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
7bf0: 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
7c00: 5f 63 68 61 6e 67 65 28 29 5d 20 69 6e 74 65 72  _change()] inter
7c10: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  face..**.** SQLi
7c20: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
7c30: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
7c40: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
7c50: 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c  thout a WHERE cl
7c60: 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70  ause.** by dropp
7c70: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
7c80: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
7c90: 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73  This is much fas
7ca0: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a  ter than going.*
7cb0: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65  * through and de
7cc0: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61  leting individua
7cd0: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72 6d 20  l elements form 
7ce0: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63  the table.)  Bec
7cf0: 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20  ause of.** this 
7d00: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
7d10: 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66  e change count f
7d20: 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  or "DELETE FROM 
7d30: 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a  table" will be.*
7d40: 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73  * zero regardles
7d50: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  s of the number 
7d60: 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74  of elements that
7d70: 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79   were originally
7d80: 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65   in the.** table
7d90: 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75  . To get an accu
7da0: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68  rate count of th
7db0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
7dc0: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a   deleted, use.**
7dd0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
7de0: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73  ble WHERE 1" ins
7df0: 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tead..**.** If a
7e00: 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d 61  nother thread ma
7e10: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
7e20: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
7e30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
7e40: 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
7e50: 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  e is running the
7e60: 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
7e70: 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ue of this routi
7e80: 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ne.** is undefin
7e90: 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
7ea0: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
7eb0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
7ec0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
7ed0: 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
7ee0: 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
7ef0: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
7f00: 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
7f10: 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
7f20: 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
7f30: 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
7f40: 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
7f50: 6f 72 74 75 6e 69 74 79 2e 20 20 54 68 69 73 20  ortunity.  This 
7f60: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
7f70: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
7f80: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
7f90: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
7fa0: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
7fb0: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
7fc0: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
7fd0: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
7fe0: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
7ff0: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
8000: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
8010: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
8020: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
8030: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
8040: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
8050: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
8060: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
8070: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
8080: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
8090: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
80a0: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
80b0: 75 74 69 6e 65 20 77 69 74 68 20 61 20 64 61 74  utine with a dat
80c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
80d0: 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
80e0: 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
80f0: 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
8100: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
8110: 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
8120: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
8130: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
8140: 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
8150: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
8160: 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  ..** If an inter
8170: 72 75 70 74 65 64 20 6f 70 65 72 61 74 69 6f 6e  rupted operation
8180: 20 77 61 73 20 61 6e 20 75 70 64 61 74 65 20 74   was an update t
8190: 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
81a0: 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
81b0: 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
81c0: 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
81d0: 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72 6f  ction will be ro
81e0: 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 61 75 74  lled.** back aut
81f0: 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2f 0a 76  omatically..*/.v
8200: 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
8210: 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
8220: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
8230: 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
8240: 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
8250: 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
8260: 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
8270: 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  s return true if
8280: 20 74 68 65 20 67 69 76 65 6e 20 69 6e 70 75 74   the given input
8290: 20 73 74 72 69 6e 67 20 63 6f 6d 70 72 69 73 65   string comprise
82a0: 73 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  s.** one or more
82b0: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
82c0: 61 74 65 6d 65 6e 74 73 2e 20 46 6f 72 20 74 68  atements. For th
82d0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  e sqlite3_comple
82e0: 74 65 28 29 20 63 61 6c 6c 2c 0a 2a 2a 20 74 68  te() call,.** th
82f0: 65 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  e parameter must
8300: 20 62 65 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   be a nul-termin
8310: 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
8320: 67 2e 20 46 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  g. For.** sqlite
8330: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2c 20  3_complete16(), 
8340: 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
8350: 20 6d 61 63 68 69 6e 65 20 62 79 74 65 20 6f 72   machine byte or
8360: 64 65 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e  der UTF-16 strin
8370: 67 0a 2a 2a 20 69 73 20 72 65 71 75 69 72 65 64  g.** is required
8380: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
8390: 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
83a0: 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69  l for command-li
83b0: 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
83c0: 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
83d0: 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
83e0: 64 20 74 65 78 74 20 66 6f 72 6d 73 20 6f 6e 65  d text forms one
83f0: 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 74   or more complet
8400: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
8410: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
8420: 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
8430: 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
8440: 69 6e 67 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ing the statemen
8450: 74 73 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  ts into.** SQLit
8460: 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 54  e for parsing. T
8470: 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73 20  he algorithm is 
8480: 73 69 6d 70 6c 65 2e 20 20 49 66 20 74 68 65 20  simple.  If the 
8490: 0a 2a 2a 20 6c 61 73 74 20 74 6f 6b 65 6e 20 6f  .** last token o
84a0: 74 68 65 72 20 74 68 61 6e 20 73 70 61 63 65 73  ther than spaces
84b0: 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 69 73   and comments is
84c0: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2c 20 74 68   a semicolon, th
84d0: 65 6e 20 72 65 74 75 72 6e 20 0a 2a 2a 20 74 72  en return .** tr
84e0: 75 65 2e 20 20 41 63 74 75 61 6c 6c 79 2c 20 74  ue.  Actually, t
84f0: 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73 20  he algorithm is 
8500: 61 20 6c 69 74 74 6c 65 20 6d 6f 72 65 20 63 6f  a little more co
8510: 6d 70 6c 69 63 61 74 65 64 20 74 68 61 6e 20 74  mplicated than t
8520: 68 61 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  hat.** in order 
8530: 74 6f 20 64 65 61 6c 20 77 69 74 68 20 74 72 69  to deal with tri
8540: 67 67 65 72 73 2c 20 62 75 74 20 74 68 65 20 62  ggers, but the b
8550: 61 73 69 63 20 69 64 65 61 20 69 73 20 74 68 65  asic idea is the
8560: 20 73 61 6d 65 3a 20 20 74 68 65 0a 2a 2a 20 73   same:  the.** s
8570: 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
8580: 63 6f 6d 70 6c 65 74 65 20 75 6e 6c 65 73 73 20  complete unless 
8590: 69 74 20 65 6e 64 73 20 69 6e 20 61 20 73 65 6d  it ends in a sem
85a0: 69 63 6f 6c 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  icolon..*/.int s
85b0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
85c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
85d0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
85e0: 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
85f0: 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
8600: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
8610: 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
8620: 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
8630: 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a  _BUSY Errors.**.
8640: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
8650: 69 64 65 6e 74 69 66 69 65 73 20 61 20 63 61 6c  identifies a cal
8660: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
8670: 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
8680: 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65 72  oked.** whenever
8690: 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
86a0: 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
86b0: 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a 2a  tabase table .**
86c0: 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
86d0: 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73 20  read or process 
86e0: 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49  has locked..** I
86f0: 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
8700: 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
8710: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
8720: 2a 2a 20 28 6f 72 20 73 6f 6d 65 74 69 6d 65 73  ** (or sometimes
8730: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
8740: 4c 4f 43 4b 45 44 5d 29 0a 2a 2a 20 69 73 20 72  LOCKED]).** is r
8750: 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
8760: 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
8770: 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 0a  ering the lock..
8780: 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63  ** If the busy c
8790: 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 4e  allback is not N
87a0: 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ULL, then the.**
87b0: 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62   callback will b
87c0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
87d0: 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  wo arguments.  T
87e0: 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75  he.** first argu
87f0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64  ment to the hand
8800: 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
8810: 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
8820: 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
8830: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
8840: 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  t to this routin
8850: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  e.  The second a
8860: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
8870: 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68 65  e handler is the
8880: 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
8890: 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
88a0: 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
88b0: 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
88c0: 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
88d0: 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73  t. If the.** bus
88e0: 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
88f0: 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
8900: 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
8910: 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
8920: 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
8930: 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
8940: 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
8950: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
8960: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
8970: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
8980: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
8990: 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
89a0: 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
89b0: 74 6f 20 6f 70 65 6e 20 74 68 65 0a 2a 2a 20 64  to open the.** d
89c0: 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
89d0: 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
89e0: 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
89f0: 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
8a00: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
8a10: 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
8a20: 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20 77 69  ee that.** it wi
8a30: 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ll be invoked wh
8a40: 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
8a50: 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20   contention..** 
8a60: 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
8a70: 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
8a80: 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
8a90: 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
8aa0: 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63   in.** a deadloc
8ab0: 6b 2c 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  k, it will retur
8ac0: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
8ad0: 69 6e 73 74 65 61 64 2e 0a 2a 2a 20 43 6f 6e 73  instead..** Cons
8ae0: 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
8af0: 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
8b00: 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
8b10: 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
8b20: 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
8b30: 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
8b40: 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
8b50: 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
8b60: 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
8b70: 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
8b80: 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
8b90: 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
8ba0: 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
8bb0: 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
8bc0: 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
8bd0: 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
8be0: 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
8bf0: 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
8c00: 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
8c10: 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
8c20: 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
8c30: 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
8c40: 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
8c50: 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
8c60: 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
8c70: 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
8c80: 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
8c90: 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
8ca0: 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
8cb0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
8cc0: 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
8cd0: 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
8ce0: 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
8cf0: 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
8d00: 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
8d10: 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
8d20: 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
8d30: 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
8d40: 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
8d50: 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  eed..**.** The d
8d60: 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
8d70: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
8d80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8d90: 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
8da0: 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
8db0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
8dc0: 44 5d 20 77 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  D] when.** SQLit
8dd0: 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
8de0: 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
8df0: 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
8e00: 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
8e10: 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
8e20: 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
8e30: 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
8e40: 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
8e50: 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
8e60: 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
8e70: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
8e80: 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
8e90: 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
8ea0: 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
8eb0: 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
8ec0: 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
8ed0: 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
8ee0: 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
8ef0: 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
8f00: 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
8f10: 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c    If it is unabl
8f20: 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
8f30: 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
8f40: 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
8f50: 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
8f60: 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
8f70: 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
8f80: 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
8f90: 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
8fa0: 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
8fb0: 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
8fc0: 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
8fd0: 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
8fe0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
8ff0: 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72  ED].  This error
9000: 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
9010: 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
9020: 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
9030: 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
9040: 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
9050: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73  ef="http://www.s
9060: 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 61  qlite.org/cvstra
9070: 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
9080: 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
9090: 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
90a0: 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
90b0: 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
90c0: 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
90d0: 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
90e0: 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
90f0: 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 53 71 6c 69 74  nt..**..** Sqlit
9100: 65 20 69 73 20 72 65 2d 65 6e 74 72 61 6e 74 2c  e is re-entrant,
9110: 20 73 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   so the busy han
9120: 64 6c 65 72 20 6d 61 79 20 73 74 61 72 74 20 61  dler may start a
9130: 20 6e 65 77 20 71 75 65 72 79 2e 20 0a 2a 2a 20   new query. .** 
9140: 28 49 74 20 69 73 20 6e 6f 74 20 63 6c 65 61 72  (It is not clear
9150: 20 77 68 79 20 61 6e 79 6f 6e 65 20 77 6f 75 6c   why anyone woul
9160: 64 20 65 76 65 72 79 20 77 61 6e 74 20 74 6f 20  d every want to 
9170: 64 6f 20 74 68 69 73 2c 20 62 75 74 20 69 74 0a  do this, but it.
9180: 2a 2a 20 69 73 20 61 6c 6c 6f 77 65 64 2c 20 69  ** is allowed, i
9190: 6e 20 74 68 65 6f 72 79 2e 29 20 20 42 75 74 20  n theory.)  But 
91a0: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
91b0: 20 6d 61 79 20 6e 6f 74 20 63 6c 6f 73 65 20 74   may not close t
91c0: 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
91d0: 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 64 61 74   Closing the dat
91e0: 61 62 61 73 65 20 66 72 6f 6d 20 61 20 62 75 73  abase from a bus
91f0: 79 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 64  y handler will d
9200: 65 6c 65 74 65 20 0a 2a 2a 20 64 61 74 61 20 73  elete .** data s
9210: 74 72 75 63 74 75 72 65 73 20 6f 75 74 20 66 72  tructures out fr
9220: 6f 6d 20 75 6e 64 65 72 20 74 68 65 20 65 78 65  om under the exe
9230: 63 75 74 69 6e 67 20 71 75 65 72 79 20 61 6e 64  cuting query and
9240: 20 77 69 6c 6c 20 0a 2a 2a 20 70 72 6f 62 61 62   will .** probab
9250: 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ly result in a s
9260: 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
9270: 74 20 6f 72 20 6f 74 68 65 72 20 72 75 6e 74 69  t or other runti
9280: 6d 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  me error..**.** 
9290: 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
92a0: 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
92b0: 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
92c0: 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73  for each databas
92d0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
92e0: 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
92f0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
9300: 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ars any previous
9310: 20 6f 6e 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68   one..** Note th
9320: 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
9330: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
9340: 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  ()] will also se
9350: 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74 68  t or clear.** th
9360: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
9370: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 6f 70 65 72 61  **.** When opera
9380: 74 69 6e 67 20 69 6e 20 5b 73 71 6c 69 74 65 33  ting in [sqlite3
9390: 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
93a0: 61 63 68 65 20 7c 20 73 68 61 72 65 64 20 63 61  ache | shared ca
93b0: 63 68 65 20 6d 6f 64 65 5d 2c 0a 2a 2a 20 6f 6e  che mode],.** on
93c0: 6c 79 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  ly a single busy
93d0: 20 68 61 6e 64 6c 65 72 20 63 61 6e 20 62 65 20   handler can be 
93e0: 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
93f0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
9400: 2a 2a 20 53 6f 20 69 66 20 74 77 6f 20 64 61 74  ** So if two dat
9410: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9420: 73 20 73 68 61 72 65 20 61 20 73 69 6e 67 6c 65  s share a single
9430: 20 63 61 63 68 65 2c 20 74 68 65 6e 20 63 68 61   cache, then cha
9440: 6e 67 69 6e 67 0a 2a 2a 20 74 68 65 20 62 75 73  nging.** the bus
9450: 79 20 68 61 6e 64 6c 65 72 20 6f 6e 20 6f 6e 65  y handler on one
9460: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69 6c 6c   connection will
9470: 20 61 6c 73 6f 20 63 68 61 6e 67 65 20 74 68 65   also change the
9480: 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
9490: 20 69 6e 20 74 68 65 20 6f 74 68 65 72 20 63 6f   in the other co
94a0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 62  nnection.  The b
94b0: 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 69  usy handler is i
94c0: 6e 76 6f 6b 65 64 0a 2a 2a 20 69 6e 20 74 68 65  nvoked.** in the
94d0: 20 74 68 72 65 61 64 20 74 68 61 74 20 77 61 73   thread that was
94e0: 20 72 75 6e 6e 69 6e 67 20 77 68 65 6e 20 74 68   running when th
94f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 77 61  e SQLITE_BUSY wa
9500: 73 20 68 69 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  s hit..*/.int sq
9510: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
9520: 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
9530: 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
9540: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
9550: 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
9560: 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
9570: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  * This routine s
9580: 65 74 73 20 61 20 62 75 73 79 20 68 61 6e 64 6c  ets a busy handl
9590: 65 72 20 74 68 61 74 20 73 6c 65 65 70 73 20 66  er that sleeps f
95a0: 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65 6e 20  or a while when 
95b0: 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c 6f  a.** table is lo
95c0: 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c  cked.  The handl
95d0: 65 72 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  er will sleep mu
95e0: 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
95f0: 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74 20  il .** at least 
9600: 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
9610: 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68 61  s of sleeping ha
9620: 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 20 41  ve been done.  A
9630: 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c  fter.** "ms" mil
9640: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
9650: 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e 64 6c  eping, the handl
9660: 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
9670: 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73 71  ch.** causes [sq
9680: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
9690: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
96a0: 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
96b0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
96c0: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74  .**.** Calling t
96d0: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
96e0: 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
96f0: 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
9700: 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
9710: 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
9720: 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ndlers..**.** Th
9730: 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
9740: 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
9750: 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
9760: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
9770: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
9780: 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
9790: 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65 66 69  handler was defi
97a0: 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e 67 20  ned  .** (using 
97b0: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
97c0: 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
97d0: 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
97e0: 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
97f0: 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
9800: 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a  ler is cleared..
9810: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
9820: 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
9830: 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
9840: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9850: 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
9860: 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
9870: 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54   Queries.**.** T
9880: 68 69 73 20 6e 65 78 74 20 72 6f 75 74 69 6e 65  his next routine
9890: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63   is a convenienc
98a0: 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  e wrapper around
98b0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
98c0: 5d 2e 0a 2a 2a 20 49 6e 73 74 65 61 64 20 6f 66  ]..** Instead of
98d0: 20 69 6e 76 6f 6b 69 6e 67 20 61 20 75 73 65 72   invoking a user
98e0: 2d 73 75 70 70 6c 69 65 64 20 63 61 6c 6c 62 61  -supplied callba
98f0: 63 6b 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20  ck for each row 
9900: 6f 66 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  of the.** result
9910: 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  , this routine r
9920: 65 6d 65 6d 62 65 72 73 20 65 61 63 68 20 72 6f  emembers each ro
9930: 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
9940: 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74  in memory.** obt
9950: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
9960: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 74  te3_malloc()], t
9970: 68 65 6e 20 72 65 74 75 72 6e 73 20 61 6c 6c 20  hen returns all 
9980: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 61 66  of the result af
9990: 74 65 72 20 74 68 65 0a 2a 2a 20 71 75 65 72 79  ter the.** query
99a0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 2e 20 0a   has finished. .
99b0: 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d  **.** As an exam
99c0: 70 6c 65 2c 20 73 75 70 70 6f 73 65 20 74 68 65  ple, suppose the
99d0: 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 77 68   query result wh
99e0: 65 72 65 20 74 68 69 73 20 74 61 62 6c 65 3a 0a  ere this table:.
99f0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
9a00: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
9a10: 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
9a20: 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
9a30: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
9a40: 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
9a50: 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
9a60: 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
9a70: 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
9a80: 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
9a90: 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
9aa0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
9ab0: 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 61  .** If the 3rd a
9ac0: 72 67 75 6d 65 6e 74 20 77 65 72 65 20 26 61 7a  rgument were &az
9ad0: 52 65 73 75 6c 74 20 74 68 65 6e 20 61 66 74 65  Result then afte
9ae0: 72 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72  r the function r
9af0: 65 74 75 72 6e 73 0a 2a 2a 20 61 7a 52 65 73 75  eturns.** azResu
9b00: 6c 74 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  lt will contain 
9b10: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 61  the following da
9b20: 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ta:.**.** <block
9b30: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
9b40: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
9b50: 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
9b60: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
9b70: 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
9b80: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
9b90: 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
9ba0: 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
9bb0: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
9bc0: 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
9bd0: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
9be0: 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
9bf0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
9c00: 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
9c10: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
9c20: 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
9c30: 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
9c40: 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
9c50: 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
9c60: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
9c70: 2a 2a 20 4e 6f 74 69 63 65 20 74 68 61 74 20 74  ** Notice that t
9c80: 68 65 72 65 20 69 73 20 61 6e 20 65 78 74 72 61  here is an extra
9c90: 20 72 6f 77 20 6f 66 20 64 61 74 61 20 63 6f 6e   row of data con
9ca0: 74 61 69 6e 69 6e 67 20 74 68 65 20 63 6f 6c 75  taining the colu
9cb0: 6d 6e 0a 2a 2a 20 68 65 61 64 65 72 73 2e 20 20  mn.** headers.  
9cc0: 42 75 74 20 74 68 65 20 2a 6e 72 6f 77 20 72 65  But the *nrow re
9cd0: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20 73 74  turn value is st
9ce0: 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f 6c 75 6d 6e  ill 3.  *ncolumn
9cf0: 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20 32 2e   is.** set to 2.
9d00: 20 20 49 6e 20 67 65 6e 65 72 61 6c 2c 20 74 68    In general, th
9d10: 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75  e number of valu
9d20: 65 73 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  es inserted into
9d30: 20 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 77 69 6c   azResult.** wil
9d40: 6c 20 62 65 20 28 28 2a 6e 72 6f 77 29 20 2b 20  l be ((*nrow) + 
9d50: 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e 29 2e 0a 2a  1)*(*ncolumn)..*
9d60: 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63  *.** After the c
9d70: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
9d80: 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
9d90: 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69  ng the result, i
9da0: 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 61 73  t should .** pas
9db0: 73 20 74 68 65 20 72 65 73 75 6c 74 20 64 61 74  s the result dat
9dc0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  a pointer to sql
9dd0: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
9de0: 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 0a 2a  ) in order to .*
9df0: 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
9e00: 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
9e10: 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61 75 73  lloc-ed.  Becaus
9e20: 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
9e30: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
9e40: 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 2c  lloc()] happens,
9e50: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
9e60: 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
9e70: 72 79 20 74 6f 20 63 61 6c 6c 20 0a 2a 2a 20 5b  ry to call .** [
9e80: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
9e90: 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 20  directly.  Only 
9ea0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
9eb0: 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
9ec0: 6f 20 72 65 6c 65 61 73 65 20 0a 2a 2a 20 74 68  o release .** th
9ed0: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
9ee0: 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
9ef0: 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76  .** The return v
9f00: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75  alue of this rou
9f10: 74 69 6e 65 20 69 73 20 74 68 65 20 73 61 6d 65  tine is the same
9f20: 20 61 73 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65   as from [sqlite
9f30: 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2f 0a 69 6e  3_exec()]..*/.in
9f40: 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
9f50: 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ble(.  sqlite3*,
9f60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
9f70: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
9f80: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
9f90: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 2f 2a  r *sql,       /*
9fa0: 20 53 51 4c 20 74 6f 20 62 65 20 65 78 65 63 75   SQL to be execu
9fb0: 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
9fc0: 2a 72 65 73 75 6c 74 70 2c 20 20 20 20 20 20 20  *resultp,       
9fd0: 2f 2a 20 52 65 73 75 6c 74 20 77 72 69 74 74 65  /* Result writte
9fe0: 6e 20 74 6f 20 61 20 63 68 61 72 20 2a 5b 5d 20  n to a char *[] 
9ff0: 20 74 68 61 74 20 74 68 69 73 20 70 6f 69 6e 74   that this point
a000: 73 20 74 6f 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e  s to */.  int *n
a010: 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 20  row,            
a020: 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
a030: 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
a040: 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
a050: 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  *ncolumn,       
a060: 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
a070: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
a080: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
a090: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
a0a0: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
a0b0: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
a0c0: 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
a0d0: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
a0e0: 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
a0f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a100: 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
a110: 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
a120: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
a130: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
a140: 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  rkalikes of the 
a150: 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
a160: 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
a170: 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
a180: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
a190: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
a1a0: 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
a1b0: 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
a1c0: 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
a1d0: 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
a1e0: 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
a1f0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
a200: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
a210: 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
a220: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
a230: 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
a240: 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
a250: 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
a260: 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72  free()].  Both r
a270: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
a280: 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
a290: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
a2a0: 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
a2b0: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
a2c0: 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
a2d0: 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
a2e0: 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
a2f0: 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70  * In sqlite3_snp
a300: 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
a310: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
a320: 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
a330: 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
a340: 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
a350: 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
a360: 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
a370: 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
a380: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
a390: 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
a3a0: 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
a3b0: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
a3c0: 74 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  ter.  Note that 
a3d0: 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
a3e0: 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
a3f0: 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
a400: 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
a410: 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61  tf().  This is a
a420: 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
a430: 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
a440: 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
a450: 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
a460: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
a470: 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65  atibility.  Note
a480: 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
a490: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
a4a0: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
a4b0: 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
a4c0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
a4d0: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
a4e0: 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
a4f0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
a500: 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64  e buffer.  We ad
a510: 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
a520: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
a530: 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
a540: 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
a550: 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
a560: 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
a570: 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
a580: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
a590: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
a5a0: 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
a5b0: 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
a5c0: 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41  ibility..**.** A
a5d0: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
a5e0: 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
a5f0: 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
a600: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
a610: 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
a620: 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
a630: 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
a640: 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
a650: 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
a660: 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
a670: 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
a680: 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
a690: 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
a6a0: 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
a6b0: 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
a6c0: 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
a6d0: 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
a6e0: 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
a6f0: 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
a700: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
a710: 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
a720: 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
a730: 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
a740: 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
a750: 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
a760: 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
a770: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
a780: 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
a790: 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d 61  ual printf forma
a7a0: 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
a7b0: 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
a7c0: 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
a7d0: 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
a7e0: 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
a7f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
a800: 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
a810: 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
a820: 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
a830: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
a840: 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
a850: 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
a860: 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
a870: 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
a880: 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
a890: 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
a8a0: 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
a8b0: 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
a8c0: 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
a8d0: 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
a8e0: 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
a8f0: 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
a900: 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
a910: 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
a920: 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
a930: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f   For example, so
a940: 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 72   some string var
a950: 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74  iable contains t
a960: 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
a970: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
a980: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
a990: 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
a9a0: 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
a9b0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
a9c0: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
a9d0: 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
a9e0: 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
a9f0: 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
aa00: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
aa10: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
aa20: 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
aa30: 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
aa40: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
aa50: 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
aa60: 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
aa70: 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
aa80: 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
aa90: 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
aaa0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
aab0: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
aac0: 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
aad0: 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
aae0: 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
aaf0: 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
ab00: 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
ab10: 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
ab20: 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
ab30: 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
ab40: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
ab50: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
ab60: 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
ab70: 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
ab80: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
ab90: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
aba0: 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
abb0: 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
abc0: 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
abd0: 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
abe0: 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
abf0: 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
ac00: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
ac10: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
ac20: 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
ac30: 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
ac40: 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
ac50: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
ac60: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
ac70: 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
ac80: 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
ac90: 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
aca0: 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68  l rule you.** sh
acb0: 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73 65 20  ould always use 
acc0: 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
acd0: 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
ace0: 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
acf0: 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a  ng .** literal..
ad00: 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74  **.** The %Q opt
ad10: 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
ad20: 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
ad30: 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
ad40: 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
ad50: 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
ad60: 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
ad70: 4f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  Or if the parame
ad80: 74 65 72 20 69 6e 20 74 68 65 20 61 72 67 75 6d  ter in the argum
ad90: 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61  ent.** list is a
ada0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
adb0: 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
adc0: 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
add0: 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a  ithout single.**
ade0: 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
adf0: 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
ae00: 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  on.  So, for exa
ae10: 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
ae20: 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
ae30: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
ae40: 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
ae50: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
ae60: 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
ae70: 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
ae80: 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
ae90: 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
aea0: 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
aeb0: 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
aec0: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
aed0: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
aee0: 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
aef0: 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
af00: 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
af10: 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
af20: 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
af30: 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
af40: 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
af50: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
af60: 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
af70: 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
af80: 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
af90: 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
afa0: 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
afb0: 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
afc0: 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
afd0: 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
afe0: 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
aff0: 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
b000: 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
b010: 74 20 73 74 72 69 6e 67 2e 0a 2a 2f 0a 63 68 61  t string..*/.cha
b020: 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
b030: 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
b040: 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
b050: 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
b060: 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
b070: 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
b080: 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
b090: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
b0a0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
b0b0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
b0c0: 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
b0d0: 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
b0e0: 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
b0f0: 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
b100: 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
b110: 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
b120: 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
b130: 74 69 6f 6e 20 6e 65 65 64 73 2e 20 54 68 65 20  tion needs. The 
b140: 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e  default implemen
b150: 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
b160: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b170: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65  on subsystem use
b180: 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20  s the malloc(), 
b190: 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64  realloc().** and
b1a0: 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64   free() provided
b1b0: 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64   by the standard
b1c0: 20 43 20 6c 69 62 72 61 72 79 2e 20 20 48 6f 77   C library.  How
b1d0: 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c  ever, if .** SQL
b1e0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
b1f0: 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69  with the followi
b200: 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  ng C preprocesso
b210: 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62  r macro.**.** <b
b220: 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54  lockquote> SQLIT
b230: 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
b240: 4c 4f 43 41 54 49 4f 4e 20 3c 2f 62 6c 6f 63 6b  LOCATION </block
b250: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 74 68 65  quote>.**.** the
b260: 6e 20 6e 6f 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n no implementat
b270: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
b280: 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
b290: 65 73 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 2e  es by.** SQLite.
b2a0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
b2b0: 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  n that links aga
b2c0: 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a  inst SQLite is.*
b2d0: 2a 20 65 78 70 65 63 74 65 64 20 74 6f 20 70 72  * expected to pr
b2e0: 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20 69 6d  ovide its own im
b2f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 49  plementation.  I
b300: 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
b310: 6e 0a 2a 2a 20 64 6f 65 73 20 70 72 6f 76 69 64  n.** does provid
b320: 65 20 69 74 73 20 6f 77 6e 20 69 6d 70 6c 65 6d  e its own implem
b330: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  entation for the
b340: 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 74 68 65  se routines, the
b350: 6e 0a 2a 2a 20 69 74 20 6d 75 73 74 20 61 6c 73  n.** it must als
b360: 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70  o provide an imp
b370: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
b380: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
b390: 72 79 5f 61 6c 61 72 6d 28 29 5d 2e 0a 2a 2a 0a  ry_alarm()]..**.
b3a0: 2a 2a 20 3c 62 3e 45 78 63 65 70 74 69 6f 6e 3a  ** <b>Exception:
b3b0: 3c 2f 62 3e 20 54 68 65 20 77 69 6e 64 6f 77 73  </b> The windows
b3c0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
b3d0: 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
b3e0: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
b3f0: 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
b400: 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
b410: 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
b420: 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
b430: 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
b440: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
b450: 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
b460: 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
b470: 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
b480: 74 69 63 75 6c 61 72 20 77 69 6e 64 6f 77 73 0a  ticular windows.
b490: 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
b4a0: 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
b4b0: 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
b4c0: 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
b4d0: 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
b4e0: 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
b4f0: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
b500: 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
b510: 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
b520: 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a  LITE_NOMEM]..*/.
b530: 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
b540: 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
b550: 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
b560: 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
b570: 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
b580: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
b590: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
b5a0: 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
b5b0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64  tics.**.** In ad
b5c0: 64 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 62 61  dition to the ba
b5d0: 73 69 63 20 74 68 72 65 65 20 61 6c 6c 6f 63 61  sic three alloca
b5e0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a 2a  tion routines .*
b5f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
b600: 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
b610: 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
b620: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c  ite3_realloc()],
b630: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
b640: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
b650: 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74  tem included wit
b660: 68 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  h the SQLite.** 
b670: 73 6f 75 72 63 65 73 20 70 72 6f 76 69 64 65 73  sources provides
b680: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
b690: 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 0a  shown below..**.
b6a0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 6f 66 20  ** The first of 
b6b0: 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
b6c0: 65 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  es returns the a
b6d0: 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20  mount of memory 
b6e0: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  .** currently ou
b6f0: 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
b700: 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
b710: 64 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a  d).  The second.
b720: 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c  ** returns the l
b730: 61 72 67 65 73 74 20 69 6e 73 74 61 6e 74 61 6e  argest instantan
b740: 65 6f 75 73 20 61 6d 6f 75 6e 74 20 6f 66 20 6f  eous amount of o
b750: 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 6d 65  utstanding.** me
b760: 6d 6f 72 79 2e 20 20 54 68 65 20 68 69 67 68 77  mory.  The highw
b770: 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
b780: 65 74 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  et if the argume
b790: 6e 74 20 69 73 0a 2a 2a 20 74 72 75 65 2e 20 20  nt is.** true.  
b7a0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
b7b0: 64 6f 65 73 20 6e 6f 74 20 75 73 65 20 65 69 74  does not use eit
b7c0: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
b7d0: 74 69 6e 65 73 0a 2a 2a 20 61 6e 64 20 73 6f 20  tines.** and so 
b7e0: 74 68 65 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  they do not have
b7f0: 20 74 6f 20 62 65 20 69 6d 70 6c 65 6d 65 6e 74   to be implement
b800: 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
b810: 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 53 51 4c 49  ation.** if SQLI
b820: 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
b830: 4c 4c 4f 43 41 54 49 4f 4e 20 69 73 20 64 65 66  LLOCATION is def
b840: 69 6e 65 64 2e 20 20 54 68 65 73 65 20 72 6f 75  ined.  These rou
b850: 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 72 6f  tines.** are pro
b860: 76 69 64 65 64 20 62 79 20 74 68 65 20 64 65 66  vided by the def
b870: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 73 75 62 73  ault memory subs
b880: 79 73 74 65 6d 20 66 6f 72 20 64 69 61 67 6e 6f  ystem for diagno
b890: 73 74 69 63 0a 2a 2a 20 70 75 72 70 6f 73 65 73  stic.** purposes
b8a0: 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
b8b0: 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
b8c0: 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
b8d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
b8e0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
b8f0: 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
b900: 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
b910: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
b920: 6f 63 61 74 69 6f 6e 20 41 6c 61 72 6d 73 0a 2a  ocation Alarms.*
b930: 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
b940: 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 5d 20  3_memory_alarm] 
b950: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20  routine is used 
b960: 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 61  to register.** a
b970: 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 6d 65 6d   callback on mem
b980: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
b990: 76 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  vents..**.** Thi
b9a0: 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
b9b0: 65 72 73 20 6f 72 20 63 6c 65 61 72 73 20 61 20  ers or clears a 
b9c0: 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 66  callbacks that f
b9d0: 69 72 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65  ires when.** the
b9e0: 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
b9f0: 79 20 61 6c 6c 6f 63 61 74 65 64 20 65 78 63 65  y allocated exce
ba00: 65 64 73 20 69 54 68 72 65 73 68 6f 6c 64 2e 20  eds iThreshold. 
ba10: 20 4f 6e 6c 79 0a 2a 2a 20 61 20 73 69 6e 67 6c   Only.** a singl
ba20: 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 62  e callback can b
ba30: 65 20 72 65 67 69 73 74 65 72 65 64 20 61 74 20  e registered at 
ba40: 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
ba50: 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
ba60: 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29  3_memory_alarm()
ba70: 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  ] overwrites the
ba80: 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 62 61   previous callba
ba90: 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  ck..** The callb
baa0: 61 63 6b 20 69 73 20 64 69 73 61 62 6c 65 64 20  ack is disabled 
bab0: 62 79 20 73 65 74 74 69 6e 67 20 78 43 61 6c 6c  by setting xCall
bac0: 62 61 63 6b 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  back to a NULL.*
bad0: 2a 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a  * pointer..** .*
bae0: 2a 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 73  * The parameters
baf0: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
bb00: 20 61 72 65 20 74 68 65 20 70 41 72 67 20 76 61   are the pArg va
bb10: 6c 75 65 2c 20 74 68 65 20 0a 2a 2a 20 61 6d 6f  lue, the .** amo
bb20: 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  unt of memory cu
bb30: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2c 20  rrently in use, 
bb40: 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  and the size of 
bb50: 74 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  the.** allocatio
bb60: 6e 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20  n that provoked 
bb70: 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  the callback.  T
bb80: 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c  he callback will
bb90: 0a 2a 2a 20 70 72 65 73 75 6d 61 62 6c 79 20 69  .** presumably i
bba0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
bbb0: 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 20 75  ree()] to free u
bbc0: 70 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 2e 0a  p memory space..
bbd0: 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
bbe0: 6d 61 79 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  may invoke [sqli
bbf0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
bc00: 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
bc10: 63 28 29 5d 0a 2a 2a 20 62 75 74 20 69 66 20 69  c()].** but if i
bc20: 74 20 64 6f 65 73 2c 20 6e 6f 20 61 64 64 69 74  t does, no addit
bc30: 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  ional callbacks 
bc40: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
bc50: 62 79 0a 2a 2a 20 74 68 65 20 72 65 63 75 72 73  by.** the recurs
bc60: 69 76 65 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a  ive calls..**.**
bc70: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   The [sqlite3_so
bc80: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d  ft_heap_limit()]
bc90: 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
bca0: 20 62 79 20 72 65 67 69 73 74 65 72 69 6e 67 0a   by registering.
bcb0: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 61 72  ** a memory alar
bcc0: 6d 20 61 74 20 74 68 65 20 73 6f 66 74 20 68 65  m at the soft he
bcd0: 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 69 6e 76  ap limit and inv
bce0: 6f 6b 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  oking .** [sqlit
bcf0: 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
bd00: 79 28 29 5d 20 69 6e 20 74 68 65 20 61 6c 61 72  y()] in the alar
bd10: 6d 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 70 70  m callback.  App
bd20: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 6f 67  lication.** prog
bd30: 72 61 6d 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  rams should not 
bd40: 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
bd50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
bd60: 72 79 5f 61 6c 61 72 6d 28 29 5d 0a 2a 2a 20 69  ry_alarm()].** i
bd70: 6e 74 65 72 66 61 63 65 20 62 65 63 61 75 73 65  nterface because
bd80: 20 64 6f 69 6e 67 20 73 6f 20 77 69 6c 6c 20 69   doing so will i
bd90: 6e 74 65 72 66 65 72 65 20 77 69 74 68 20 74 68  nterfere with th
bda0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f  e.** [sqlite3_so
bdb0: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d  ft_heap_limit()]
bdc0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 69 73 20 69   module.  This i
bdd0: 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 6f  nterface is expo
bde0: 73 65 64 0a 2a 2a 20 6f 6e 6c 79 20 73 6f 20 74  sed.** only so t
bdf0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
be00: 20 63 61 6e 20 70 72 6f 76 69 64 65 20 74 68 65   can provide the
be10: 69 72 20 6f 77 6e 0a 2a 2a 20 61 6c 74 65 72 6e  ir own.** altern
be20: 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ative implementa
be30: 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 53 51  tion when the SQ
be40: 4c 69 74 65 20 63 6f 72 65 20 69 73 0a 2a 2a 20  Lite core is.** 
be50: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 53 51  compiled with SQ
be60: 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
be70: 5f 41 4c 4c 4f 43 41 54 49 4f 4e 2e 0a 2a 2f 0a  _ALLOCATION..*/.
be80: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
be90: 72 79 5f 61 6c 61 72 6d 28 0a 20 20 76 6f 69 64  ry_alarm(.  void
bea0: 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 76 6f 69  (*xCallback)(voi
beb0: 64 20 2a 70 41 72 67 2c 20 73 71 6c 69 74 65 33  d *pArg, sqlite3
bec0: 5f 69 6e 74 36 34 20 75 73 65 64 2c 20 69 6e 74  _int64 used, int
bed0: 20 4e 29 2c 0a 20 20 76 6f 69 64 20 2a 70 41 72   N),.  void *pAr
bee0: 67 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74  g,.  sqlite3_int
bef0: 36 34 20 69 54 68 72 65 73 68 6f 6c 64 0a 29 3b  64 iThreshold.);
bf00: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
bf10: 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
bf20: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
bf30: 6c 6c 62 61 63 6b 73 0a 2a 2a 2a 0a 2a 2a 20 54  llbacks.***.** T
bf40: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
bf50: 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a  sters a authoriz
bf60: 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
bf70: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
bf80: 61 72 79 2e 20 20 0a 2a 2a 20 54 68 65 20 61 75  ary.  .** The au
bf90: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
bfa0: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
bfb0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
bfc0: 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
bfd0: 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
bfe0: 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
bff0: 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
c000: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
c010: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
c020: 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
c030: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
c040: 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76  e16_v2()].  At v
c050: 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
c060: 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
c070: 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
c080: 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
c090: 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
c0a0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
c0b0: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
c0c0: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
c0d0: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
c0e0: 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
c0f0: 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
c100: 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72  wed.  The author
c110: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
c120: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 53  ould.** return S
c130: 51 4c 49 54 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f  QLITE_OK to allo
c140: 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
c150: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
c160: 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
c170: 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
c180: 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
c190: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
c1a0: 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
c1b0: 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
c1c0: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
c1d0: 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
c1e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
c1f0: 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
c200: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
c210: 20 0a 2a 2a 0a 2a 2a 20 44 65 70 65 6e 64 69 6e   .**.** Dependin
c220: 67 20 6f 6e 20 74 68 65 20 61 63 74 69 6f 6e 2c  g on the action,
c230: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   the [SQLITE_IGN
c240: 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  ORE] and [SQLITE
c250: 5f 44 45 4e 59 5d 20 72 65 74 75 72 6e 0a 2a 2a  _DENY] return.**
c260: 20 63 6f 64 65 73 20 6d 69 67 68 74 20 6d 65 61   codes might mea
c270: 6e 20 73 6f 6d 65 74 68 69 6e 67 20 64 69 66 66  n something diff
c280: 65 72 65 6e 74 20 6f 72 20 74 68 65 79 20 6d 69  erent or they mi
c290: 67 68 74 20 6d 65 61 6e 20 74 68 65 20 73 61 6d  ght mean the sam
c2a0: 65 0a 2a 2a 20 74 68 69 6e 67 2e 20 20 49 66 20  e.** thing.  If 
c2b0: 74 68 65 20 61 63 74 69 6f 6e 20 69 73 2c 20 66  the action is, f
c2c0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 70  or example, to p
c2d0: 65 72 66 6f 72 6d 20 61 20 64 65 6c 65 74 65 20  erform a delete 
c2e0: 6f 70 65 72 74 69 6f 6e 2c 0a 2a 2a 20 74 68 65  opertion,.** the
c2f0: 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
c300: 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45  ] and [SQLITE_DE
c310: 4e 59 5d 20 62 6f 74 68 20 63 61 75 73 65 20 74  NY] both cause t
c320: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  he statement com
c330: 70 69 6c 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66  pilation.** to f
c340: 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
c350: 72 2e 20 20 42 75 74 20 69 66 20 74 68 65 20 61  r.  But if the a
c360: 63 74 69 6f 6e 20 69 73 20 74 6f 20 72 65 61 64  ction is to read
c370: 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75   a specific colu
c380: 6d 6e 0a 2a 2a 20 66 72 6f 6d 20 61 20 73 70 65  mn.** from a spe
c390: 63 69 66 69 63 20 74 61 62 6c 65 2c 20 74 68 65  cific table, the
c3a0: 6e 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  n [SQLITE_DENY] 
c3b0: 77 69 6c 6c 20 63 61 75 73 65 20 74 68 65 20 65  will cause the e
c3c0: 6e 74 69 72 65 0a 2a 2a 20 73 74 61 74 65 6d 65  ntire.** stateme
c3d0: 6e 74 20 74 6f 20 66 61 69 6c 20 62 75 74 20 5b  nt to fail but [
c3e0: 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 77  SQLITE_IGNORE] w
c3f0: 69 6c 6c 20 63 61 75 73 65 20 61 20 4e 55 4c 4c  ill cause a NULL
c400: 20 76 61 6c 75 65 20 74 6f 20 62 65 0a 2a 2a 20   value to be.** 
c410: 72 65 61 64 20 69 6e 73 74 65 61 64 20 6f 66 20  read instead of 
c420: 74 68 65 20 61 63 74 75 61 6c 20 63 6f 6c 75 6d  the actual colum
c430: 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  n value..**.** T
c440: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
c450: 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
c460: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
c470: 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
c480: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
c490: 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
c4a0: 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
c4b0: 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  ) interface..** 
c4c0: 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
c4d0: 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
c4e0: 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
c4f0: 65 72 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  er .** [SQLITE_C
c500: 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
c510: 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
c520: 73 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  s the particular
c530: 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65   action.** to be
c540: 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
c550: 65 20 61 76 61 69 6c 61 62 6c 65 20 61 63 74 69  e available acti
c560: 6f 6e 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  on codes are.** 
c570: 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 64  [SQLITE_COPY | d
c580: 6f 63 75 6d 65 6e 74 65 64 20 73 65 70 61 72 61  ocumented separa
c590: 74 65 6c 79 5d 2e 20 20 54 68 65 20 74 68 69 72  tely].  The thir
c5a0: 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 0a  d through sixth.
c5b0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ** parameters to
c5c0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
c5d0: 65 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  e strings that c
c5e0: 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
c5f0: 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
c600: 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
c610: 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
c620: 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
c630: 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
c640: 20 70 72 65 70 61 72 69 6e 67 20 53 51 4c 20 73   preparing SQL s
c650: 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
c660: 6e 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73  n untrusted.** s
c670: 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
c680: 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
c690: 61 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20  atements do not 
c6a0: 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
c6b0: 74 61 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20  ta.** that they 
c6c0: 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
c6d0: 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
c6e0: 74 68 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20  they do not try 
c6f0: 74 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61  to.** execute ma
c700: 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
c710: 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
c720: 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
c730: 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
c740: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
c750: 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
c760: 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
c770: 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
c780: 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
c790: 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
c7a0: 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
c7b0: 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
c7c0: 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
c7d0: 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
c7e0: 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
c7f0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
c800: 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
c810: 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
c820: 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
c830: 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
c840: 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
c850: 20 62 65 69 6e 67 20 70 72 65 70 61 72 65 64 20   being prepared 
c860: 74 68 61 74 20 64 69 73 61 6c 6c 6f 77 73 20 65  that disallows e
c870: 76 65 72 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63  verything.** exc
c880: 65 70 74 20 53 45 4c 45 43 54 20 73 74 61 74 65  ept SELECT state
c890: 6d 65 6e 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f  ments.  .**.** O
c8a0: 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
c8b0: 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
c8c0: 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
c8d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c8e0: 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
c8f0: 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
c900: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
c910: 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
c920: 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
c930: 6c 6c 2e 20 20 41 20 4e 55 4c 4c 20 61 75 74 68  ll.  A NULL auth
c940: 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61  orizer means tha
c950: 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69  t no authorizati
c960: 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  on.** callback i
c970: 73 20 69 6e 76 6f 6b 65 64 2e 20 20 54 68 65 20  s invoked.  The 
c980: 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a  default authoriz
c990: 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  er is NULL..**.*
c9a0: 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
c9b0: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
c9c0: 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
c9d0: 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b  nly during .** [
c9e0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
c9f0: 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
ca00: 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
ca10: 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
ca20: 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
ca30: 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
ca40: 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
ca50: 74 65 70 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  tep()]..*/.int s
ca60: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
ca70: 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
ca80: 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
ca90: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
caa0: 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
cab0: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
cac0: 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
cad0: 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
cae0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
caf0: 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
cb00: 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
cb10: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
cb20: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
cb30: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
cb40: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
cb50: 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
cb60: 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
cb70: 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
cb80: 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
cb90: 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
cba0: 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
cbb0: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
cbc0: 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
cbd0: 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
cbe0: 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
cbf0: 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
cc00: 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
cc10: 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
cc20: 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
cc30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
cc40: 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
cc50: 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
cc60: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
cc70: 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
cc80: 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
cc90: 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
cca0: 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
ccb0: 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
ccc0: 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
ccd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
cce0: 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
ccf0: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
cd00: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
cd10: 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
cd20: 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
cd30: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
cd40: 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
cd50: 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
cd60: 72 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  r certain SQL st
cd70: 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
cd80: 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
cd90: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
cda0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
cdb0: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
cdc0: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
cdd0: 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
cde0: 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
cdf0: 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
ce00: 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
ce10: 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
ce20: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
ce30: 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
ce40: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
ce50: 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
ce60: 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
ce70: 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
ce80: 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75   is to be .** au
ce90: 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
cea0: 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
ceb0: 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
cec0: 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62  horization callb
ced0: 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
cee0: 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
cef0: 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
cf00: 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
cf10: 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
cf20: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
cf30: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
cf40: 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
cf50: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
cf60: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
cf70: 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
cf80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
cf90: 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a  main", "temp", .
cfa0: 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
cfb0: 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68  icable.  The 6th
cfc0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
cfd0: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
cfe0: 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
cff0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
d000: 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
d010: 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
d020: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
d030: 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
d040: 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
d050: 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
d060: 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
d070: 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76  from .** top-lev
d080: 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
d090: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
d0a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d0b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
d0c0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
d0d0: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
d0e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
d0f0: 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
d100: 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
d110: 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
d120: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
d130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
d140: 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
d150: 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
d160: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
d170: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
d180: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
d190: 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
d1a0: 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
d1b0: 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
d1c0: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
d1d0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
d1e0: 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
d1f0: 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
d200: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
d210: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
d220: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
d230: 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
d240: 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
d250: 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
d260: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
d270: 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
d280: 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
d290: 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
d2a0: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
d2b0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
d2c0: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
d2d0: 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
d2e0: 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
d2f0: 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
d300: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
d310: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
d320: 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
d330: 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
d340: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
d350: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
d360: 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
d370: 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
d380: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
d390: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
d3a0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
d3b0: 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
d3c0: 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
d3d0: 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
d3e0: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
d3f0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
d400: 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
d410: 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
d420: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
d430: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
d440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d450: 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
d460: 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
d470: 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
d480: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
d490: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d4a0: 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
d4b0: 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
d4c0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
d4d0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
d4e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d4f0: 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
d500: 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
d510: 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
d520: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
d530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d540: 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
d550: 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
d560: 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
d570: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
d580: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
d590: 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
d5a0: 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
d5b0: 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
d5c0: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
d5d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
d5e0: 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
d5f0: 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
d600: 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
d610: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
d620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
d630: 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
d640: 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
d650: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
d660: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
d670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
d680: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
d690: 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
d6a0: 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
d6b0: 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
d6c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
d6d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d6e0: 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
d6f0: 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
d700: 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
d710: 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
d720: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d730: 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
d740: 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
d750: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
d760: 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
d770: 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
d780: 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
d790: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
d7a0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
d7b0: 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
d7c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
d7d0: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
d7e0: 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
d7f0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
d800: 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
d810: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
d820: 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
d830: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
d840: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
d850: 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
d860: 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
d870: 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
d880: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
d890: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
d8a0: 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
d8b0: 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
d8c0: 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
d8d0: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
d8e0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
d8f0: 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
d900: 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
d910: 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
d920: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
d930: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d940: 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
d950: 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
d960: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
d970: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
d980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d990: 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
d9a0: 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
d9b0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
d9c0: 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
d9d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d9e0: 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
d9f0: 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
da00: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
da10: 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
da20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
da30: 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
da40: 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e       31   /* Fun
da50: 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c  ction Name   NUL
da60: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
da70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
da80: 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
da90: 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
daa0: 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
dab0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
dac0: 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
dad0: 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
dae0: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
daf0: 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
db00: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
db10: 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
db20: 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
db30: 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
db40: 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
db50: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
db60: 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
db70: 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
db80: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
db90: 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
dba0: 0a 2a 2a 20 61 74 20 74 68 65 20 66 69 72 73 74  .** at the first
dbb0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
dbc0: 5d 20 66 6f 72 20 74 68 65 20 65 76 61 6c 75 61  ] for the evalua
dbd0: 74 69 6f 6e 20 6f 66 20 61 6e 20 53 51 4c 20 73  tion of an SQL s
dbe0: 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  tatement..** The
dbf0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
dc00: 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
dc10: 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
dc20: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
dc30: 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
dc40: 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 20  tement finishes 
dc50: 61 6e 64 20 69 6e 63 6c 75 64 65 73 0a 2a 2a 20  and includes.** 
dc60: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6f 6e 20 68  information on h
dc70: 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
dc80: 74 65 6d 65 6e 74 20 72 61 6e 2e 0a 2a 2a 0a 2a  tement ran..**.*
dc90: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
dca0: 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73 20 63  ofile() API is c
dcb0: 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
dcc0: 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
dcd0: 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65   and.** is subje
dce0: 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f  ct to change..*/
dcf0: 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
dd00: 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
dd10: 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
dd20: 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
dd30: 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
dd40: 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
dd50: 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
dd60: 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
dd70: 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
dd80: 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
dd90: 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
dda0: 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
ddb0: 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
ddc0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
ddd0: 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61  ine configures a
dde0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
ddf0: 6f 6e 20 2d 20 74 68 65 20 70 72 6f 67 72 65 73  on - the progres
de00: 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61  s callback - tha
de10: 74 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20  t.** is invoked 
de20: 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
de30: 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
de40: 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
de50: 65 33 5f 65 78 65 63 28 29 5d 2c 0a 2a 2a 20 5b  e3_exec()],.** [
de60: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
de70: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
de80: 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65  _table()].  An e
de90: 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
dea0: 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63  his .** interfac
deb0: 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
dec0: 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
ded0: 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
dee0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
def0: 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
df00: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
df10: 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c   every N virtual
df20: 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73   machine opcodes
df30: 2c 0a 2a 2a 20 77 68 65 72 65 20 4e 20 69 73 20  ,.** where N is 
df40: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
df50: 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ent to this func
df60: 74 69 6f 6e 2e 20 54 68 65 20 70 72 6f 67 72 65  tion. The progre
df70: 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  ss callback.** i
df80: 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66  tself is identif
df90: 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64  ied by the third
dfa0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
dfb0: 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  s function. The 
dfc0: 66 6f 75 72 74 68 0a 2a 2a 20 61 72 67 75 6d 65  fourth.** argume
dfd0: 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  nt to this funct
dfe0: 69 6f 6e 20 69 73 20 61 20 76 6f 69 64 20 70 6f  ion is a void po
dff0: 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  inter passed to 
e000: 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
e010: 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
e020: 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74 20 69  n each time it i
e030: 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
e040: 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   If a call to [s
e050: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
e060: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
e070: 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 67 65  , or [sqlite3_ge
e080: 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 72 65  t_table()].** re
e090: 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74  sults in fewer t
e0a0: 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 20 62 65  han N opcodes be
e0b0: 69 6e 67 20 65 78 65 63 75 74 65 64 2c 20 74 68  ing executed, th
e0c0: 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  en the progress 
e0d0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
e0e0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a  never invoked..*
e0f0: 2a 20 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  * .** Only a sin
e100: 67 6c 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  gle progress cal
e110: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
e120: 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
e130: 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 6f 70 65   for each.** ope
e140: 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
e150: 63 74 69 6f 6e 2e 20 20 45 76 65 72 79 20 63 61  ction.  Every ca
e160: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  ll to sqlite3_pr
e170: 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
e180: 0a 2a 2a 20 6f 76 65 72 77 72 69 74 65 73 20 74  .** overwrites t
e190: 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 74 68  he results of th
e1a0: 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  e previous call.
e1b0: 0a 2a 2a 20 54 6f 20 72 65 6d 6f 76 65 20 74 68  .** To remove th
e1c0: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
e1d0: 61 63 6b 20 61 6c 74 6f 67 65 74 68 65 72 2c 20  ack altogether, 
e1e0: 70 61 73 73 20 4e 55 4c 4c 20 61 73 20 74 68 65  pass NULL as the
e1f0: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
e200: 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  nt to this funct
e210: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
e220: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
e230: 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65  ack returns a re
e240: 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20  sult other than 
e250: 30 2c 20 74 68 65 6e 20 74 68 65 20 63 75 72 72  0, then the curr
e260: 65 6e 74 20 0a 2a 2a 20 71 75 65 72 79 20 69 73  ent .** query is
e270: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 74 65 72   immediately ter
e280: 6d 69 6e 61 74 65 64 20 61 6e 64 20 61 6e 79 20  minated and any 
e290: 64 61 74 61 62 61 73 65 20 63 68 61 6e 67 65 73  database changes
e2a0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
e2b0: 20 54 68 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   The containing 
e2c0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
e2d0: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
e2e0: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
e2f0: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
e300: 63 61 6c 6c 20 72 65 74 75 72 6e 73 20 53 51 4c  call returns SQL
e310: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 2e 20 20  ITE_INTERRUPT.  
e320: 20 54 68 69 73 20 66 65 61 74 75 72 65 0a 2a 2a   This feature.**
e330: 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 66 6f   can be used, fo
e340: 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 69 6d  r example, to im
e350: 70 6c 65 6d 65 6e 74 20 74 68 65 20 22 43 61 6e  plement the "Can
e360: 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
e370: 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 64 69 61  .** progress dia
e380: 6c 6f 67 20 62 6f 78 20 69 6e 20 61 20 47 55 49  log box in a GUI
e390: 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
e3a0: 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
e3b0: 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
e3c0: 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
e3d0: 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
e3e0: 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
e3f0: 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
e400: 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
e410: 2a 20 4f 70 65 6e 20 74 68 65 20 73 71 6c 69 74  * Open the sqlit
e420: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
e430: 22 66 69 6c 65 6e 61 6d 65 22 2e 20 20 54 68 65  "filename".  The
e440: 20 22 66 69 6c 65 6e 61 6d 65 22 20 69 73 20 55   "filename" is U
e450: 54 46 2d 38 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  TF-8.** encoded 
e460: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
e470: 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20 65 6e  () and UTF-16 en
e480: 63 6f 64 65 64 20 69 6e 20 74 68 65 20 6e 61 74  coded in the nat
e490: 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
e4a0: 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  * for sqlite3_op
e4b0: 65 6e 31 36 28 29 2e 20 20 41 6e 20 5b 73 71 6c  en16().  An [sql
e4c0: 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 69 73  ite3*] handle is
e4d0: 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
e4e0: 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20 61  Db, even.** if a
e4f0: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
e500: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
e510: 69 73 20 6f 70 65 6e 65 64 20 28 6f 72 20 63 72  is opened (or cr
e520: 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
e530: 6c 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53 51  lly,.** then [SQ
e540: 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
e550: 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65 20  rned. Otherwise 
e560: 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  an error code is
e570: 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 0a 2a   returned. The.*
e580: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
e590: 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
e5a0: 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 20 72 6f  _errmsg16()]  ro
e5b0: 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
e5c0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
e5d0: 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
e5e0: 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
e5f0: 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  of the error..**
e600: 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
e610: 61 73 65 20 66 69 6c 65 20 64 6f 65 73 20 6e 6f  ase file does no
e620: 74 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 20  t exist, then a 
e630: 6e 65 77 20 64 61 74 61 62 61 73 65 20 77 69 6c  new database wil
e640: 6c 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20  l be created.** 
e650: 61 73 20 6e 65 65 64 65 64 2e 20 20 54 68 65 20  as needed.  The 
e660: 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
e670: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
e680: 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  e will be UTF-8 
e690: 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  if.** sqlite3_op
e6a0: 65 6e 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  en() is called a
e6b0: 6e 64 20 55 54 46 2d 31 36 20 69 66 20 73 71 6c  nd UTF-16 if sql
e6c0: 69 74 65 33 5f 6f 70 65 6e 31 36 20 69 73 20 75  ite3_open16 is u
e6d0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
e6e0: 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
e6f0: 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
e700: 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
e710: 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61 74 65  ources associate
e720: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
e730: 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20  qlite3*] handle 
e740: 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
e750: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 74  ed by passing it
e760: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
e770: 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
e780: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
e790: 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
e7a0: 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
e7b0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
e7c0: 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
e7d0: 5f 6f 70 65 6e 28 29 20 65 78 63 65 70 74 20 74  _open() except t
e7e0: 68 61 74 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20  hat.** provides 
e7f0: 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
e800: 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
e810: 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
e820: 20 6f 76 65 72 20 74 68 65 0a 2a 2a 20 6e 65 77   over the.** new
e830: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e840: 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73  tion.  The flags
e850: 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
e860: 65 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20  e one of:.**.** 
e870: 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ol>.** <li>  [S
e880: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
e890: 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NLY].** <li>  [S
e8a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
e8b0: 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RITE].** <li>  [
e8c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
e8d0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
e8e0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a  _OPEN_CREATE].**
e8f0: 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ol>.**.** The
e900: 20 66 69 72 73 74 20 76 61 6c 75 65 20 6f 70 65   first value ope
e910: 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ns the database 
e920: 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 49 66 20 74  read-only.  If t
e930: 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
e940: 0a 2a 2a 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  .** not previous
e950: 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  ly exist, an err
e960: 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  or is returned. 
e970: 20 54 68 65 20 73 65 63 6f 6e 64 20 6f 70 74 69   The second opti
e980: 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20  on opens.** the 
e990: 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
e9a0: 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
e9b0: 20 62 75 74 20 74 68 65 20 64 61 74 61 62 61 73   but the databas
e9c0: 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 0a 2a  e must already.*
e9d0: 2a 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65 72  * exist or an er
e9e0: 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
e9f0: 20 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69    The third opti
ea00: 6f 6e 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74  on opens the dat
ea10: 61 62 61 73 65 0a 2a 2a 20 66 6f 72 20 72 65 61  abase.** for rea
ea20: 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
ea30: 20 61 6e 64 20 63 72 65 61 74 65 73 20 69 74 20   and creates it 
ea40: 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  if it does not a
ea50: 6c 72 65 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a  lready exist..**
ea60: 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f   The third optio
ea70: 6e 73 20 69 73 20 62 65 68 61 76 69 6f 72 20 74  ns is behavior t
ea80: 68 61 74 20 69 73 20 75 73 65 64 20 61 6c 77 61  hat is used alwa
ea90: 79 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ys for sqlite3_o
eaa0: 70 65 6e 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c  pen().** and sql
eab0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 0a 2a  ite3_open16()..*
eac0: 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
ead0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
eae0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
eaf0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
eb00: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
eb10: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
eb20: 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
eb30: 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20  ting system .** 
eb40: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
eb50: 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
eb60: 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
eb70: 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 0a 2a  d use.  If the.*
eb80: 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
eb90: 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  er is a NULL poi
eba0: 6e 74 65 72 20 74 68 65 6e 20 61 20 64 65 66 61  nter then a defa
ebb0: 75 6c 74 20 73 75 69 74 61 62 6c 65 20 66 6f 72  ult suitable for
ebc0: 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 65 6e 76  .** the host env
ebd0: 69 72 6f 6e 6d 65 6e 74 20 69 73 20 73 75 62 73  ironment is subs
ebe0: 74 69 74 75 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e  tituted..**.** N
ebf0: 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77 73 20 75  ote to windows u
ec00: 73 65 72 73 3a 20 20 54 68 65 20 65 6e 63 6f 64  sers:  The encod
ec10: 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
ec20: 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
ec30: 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
ec40: 5f 6f 70 65 6e 28 29 20 6d 75 73 74 20 62 65 20  _open() must be 
ec50: 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
ec60: 76 65 72 20 63 6f 64 65 70 61 67 65 20 69 73 20  ver codepage is 
ec70: 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 65 66  currently.** def
ec80: 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
ec90: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
eca0: 72 6e 61 74 69 6f 6e 61 6c 20 63 68 61 72 61 63  rnational charac
ecb0: 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
ecc0: 76 65 72 74 65 64 0a 2a 2a 20 74 6f 20 55 54 46  verted.** to UTF
ecd0: 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
ece0: 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 20 73 71  ing them into sq
ecf0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2f  lite3_open()..*/
ed00: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
ed10: 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
ed20: 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
ed30: 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
ed40: 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
ed50: 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
ed60: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
ed70: 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
ed80: 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
ed90: 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
eda0: 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
edb0: 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
edc0: 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
edd0: 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
ede0: 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
edf0: 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
ee00: 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
ee10: 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
ee20: 32 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  2(.  const void 
ee30: 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
ee40: 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
ee50: 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
ee60: 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
ee70: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
ee80: 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
ee90: 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
eea0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
eeb0: 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
eec0: 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
eed0: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
eee0: 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
eef0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
ef00: 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
ef10: 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
ef20: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ef30: 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
ef40: 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
ef50: 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51  e numeric.** [SQ
ef60: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
ef70: 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54   code] or [SQLIT
ef80: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
ef90: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
efa0: 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ode].** for the 
efb0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
efc0: 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
efd0: 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
efe0: 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74 65  .** with [sqlite
eff0: 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e 20  3] handle 'db'. 
f000: 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
f010: 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20  call failed but 
f020: 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
f030: 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
f040: 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
f050: 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
f060: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a  ite3_errcode().*
f070: 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  * is undefined. 
f080: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f090: 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
f0a0: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
f0b0: 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
f0c0: 68 2d 6c 61 6e 67 61 75 67 65 0a 2a 2a 20 74 65  h-langauge.** te
f0d0: 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
f0e0: 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
f0f0: 65 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55  either UTF8 or U
f100: 54 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  TF16 respectivel
f110: 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20  y..** Memory to 
f120: 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
f130: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
f140: 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
f150: 6c 6c 79 2e 20 20 54 68 65 20 0a 2a 2a 20 73 74  lly.  The .** st
f160: 72 69 6e 67 20 6d 61 79 20 62 65 20 6f 76 65 72  ring may be over
f170: 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
f180: 6f 63 61 74 65 64 20 62 79 20 73 75 62 73 65 71  ocated by subseq
f190: 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 53 51  uent calls to SQ
f1a0: 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  Lite.** interfac
f1b0: 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  e functions..**.
f1c0: 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 6d 61 6e 79  ** Calls to many
f1d0: 20 73 71 6c 69 74 65 33 5f 2a 20 66 75 6e 63 74   sqlite3_* funct
f1e0: 69 6f 6e 73 20 73 65 74 20 74 68 65 20 65 72 72  ions set the err
f1f0: 6f 72 20 63 6f 64 65 20 61 6e 64 20 73 74 72 69  or code and stri
f200: 6e 67 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ng returned.** b
f210: 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  y [sqlite3_errco
f220: 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
f230: 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b  errmsg()], and [
f240: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
f250: 28 29 5d 0a 2a 2a 20 28 6f 76 65 72 77 72 69 74  ()].** (overwrit
f260: 69 6e 67 20 74 68 65 20 70 72 65 76 69 6f 75 73  ing the previous
f270: 20 76 61 6c 75 65 73 29 2e 20 4e 6f 74 65 20 74   values). Note t
f280: 68 61 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hat calls to [sq
f290: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
f2a0: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  ,.** [sqlite3_er
f2b0: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
f2c0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
f2d0: 5d 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  ] themselves do 
f2e0: 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 0a 2a  not affect the.*
f2f0: 2a 20 72 65 73 75 6c 74 73 20 6f 66 20 66 75 74  * results of fut
f300: 75 72 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e  ure invocations.
f310: 20 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72    Calls to API r
f320: 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20  outines that do 
f330: 6e 6f 74 20 72 65 74 75 72 6e 0a 2a 2a 20 61 6e  not return.** an
f340: 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61   error code (exa
f350: 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64  mple: [sqlite3_d
f360: 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f  ata_count()]) do
f370: 20 6e 6f 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74   not.** change t
f380: 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 72 65  he error code re
f390: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
f3a0: 6f 75 74 69 6e 65 2e 20 20 49 6e 74 65 72 66 61  outine.  Interfa
f3b0: 63 65 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ces that are.** 
f3c0: 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  not associated w
f3d0: 69 74 68 20 61 20 73 70 65 63 69 66 69 63 20 64  ith a specific d
f3e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f3f0: 6f 6e 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a  on (examples:.**
f400: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
f410: 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  f()] or [sqlite3
f420: 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
f430: 61 63 68 65 28 29 5d 20 64 6f 20 6e 6f 74 20 63  ache()] do not c
f440: 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
f450: 75 72 6e 20 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a  urn code.  .**.*
f460: 2a 20 41 73 73 75 6d 69 6e 67 20 6e 6f 20 6f 74  * Assuming no ot
f470: 68 65 72 20 69 6e 74 65 72 76 65 6e 69 6e 67 20  her intervening 
f480: 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
f490: 6c 6c 73 20 61 72 65 20 6d 61 64 65 2c 20 74 68  lls are made, th
f4a0: 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
f4b0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
f4c0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 73 73   function is ass
f4d0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
f4e0: 20 73 61 6d 65 20 65 72 72 6f 72 20 61 73 0a 2a   same error as.*
f4f0: 2a 20 74 68 65 20 73 74 72 69 6e 67 73 20 72 65  * the strings re
f500: 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
f510: 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
f520: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
f530: 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
f540: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
f550: 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
f560: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
f570: 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
f580: 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
f590: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
f5a0: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
f5b0: 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
f5c0: 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
f5d0: 2a 2a 0a 2a 2a 20 49 6e 73 74 61 6e 63 65 20 6f  **.** Instance o
f5e0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
f5f0: 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65 20 53  present single S
f600: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
f610: 54 68 69 73 0a 2a 2a 20 69 73 20 76 61 72 69 6f  This.** is vario
f620: 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
f630: 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
f640: 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63  ent" or a .** "c
f650: 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
f660: 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
f670: 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
f680: 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69  "..** .** The li
f690: 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
f6a0: 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
f6b0: 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
f6c0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
f6d0: 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
f6e0: 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
f6f0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
f700: 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
f710: 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
f720: 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
f730: 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
f740: 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e 67  parameters using
f750: 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
f760: 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
f770: 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74  lite3_bind_* int
f780: 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69  erfaces]..** <li
f790: 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
f7a0: 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
f7b0: 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
f7c0: 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
f7d0: 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
f7e0: 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
f7f0: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
f800: 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
f810: 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
f820: 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
f830: 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
f840: 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
f850: 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
f860: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
f870: 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
f880: 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
f890: 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
f8a0: 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
f8b0: 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
f8c0: 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
f8d0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
f8e0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
f8f0: 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
f900: 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
f910: 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
f920: 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
f930: 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
f940: 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
f950: 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
f960: 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
f970: 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
f980: 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
f990: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
f9a0: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73   .**.** The firs
f9b0: 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22 20  t argument "db" 
f9c0: 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 20 7c  is an [sqlite3 |
f9d0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
f9e0: 20 68 61 6e 64 6c 65 5d 20 0a 2a 2a 20 6f 62 74   handle] .** obt
f9f0: 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
fa00: 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  or call to [sqli
fa10: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b  te3_open()] or [
fa20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
fa30: 5d 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  ]..** The second
fa40: 20 61 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22   argument "zSql"
fa50: 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
fa60: 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
fa70: 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
fa80: 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
fa90: 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
faa0: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
fab0: 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
fac0: 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
fad0: 66 61 63 65 73 20 75 73 65 73 20 55 54 46 2d 38  faces uses UTF-8
fae0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
faf0: 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
fb00: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
fb10: 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
fb20: 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  6..**.** If the 
fb30: 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
fb40: 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a  s less.** than z
fb50: 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
fb60: 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
fb70: 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
fb80: 69 6e 61 74 6f 72 2e 20 20 49 66 0a 2a 2a 20 6e  inator.  If.** n
fb90: 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
fba0: 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
fbb0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
fbc0: 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73  ber of .** bytes
fbd0: 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
fbe0: 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20    When nByte is 
fbf0: 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
fc00: 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
fc10: 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
fc20: 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
fc30: 20 63 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a   character or .*
fc40: 2a 20 75 6e 74 69 6c 20 74 68 65 20 6e 42 79 74  * until the nByt
fc50: 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
fc60: 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
fc70: 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20  ..**.** *pzTail 
fc80: 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
fc90: 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
fca0: 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
fcb0: 6f 66 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  of the first.** 
fcc0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
fcd0: 20 7a 53 71 6c 2e 20 20 54 68 69 73 20 72 6f 75   zSql.  This rou
fce0: 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c  tine only compil
fcf0: 65 73 20 74 68 65 20 66 69 72 73 74 20 73 74 61  es the first sta
fd00: 74 65 6d 65 6e 74 0a 2a 2a 20 69 6e 20 7a 53 71  tement.** in zSq
fd10: 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
fd20: 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
fd30: 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  o what remains u
fd40: 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
fd50: 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
fd60: 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
fd70: 6f 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c  ompiled .** [sql
fd80: 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
fd90: 73 74 61 74 65 6d 65 6e 74 20 73 74 72 75 63 74  statement struct
fda0: 75 72 65 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ure] that can be
fdb0: 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
fdc0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
fdd0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72  ()].  Or if ther
fde0: 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
fdf0: 70 70 53 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a  ppStmt may be.**
fe00: 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49   set to NULL.  I
fe10: 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
fe20: 20 63 6f 6e 74 61 69 6e 65 64 20 6e 6f 20 53 51   contained no SQ
fe30: 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
fe40: 69 73 20 61 6e 64 0a 2a 2a 20 65 6d 70 74 79 20  is and.** empty 
fe50: 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
fe60: 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
fe70: 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
fe80: 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  .  The calling.*
fe90: 2a 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  * procedure is r
fea0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
feb0: 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
fec0: 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
fed0: 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  nt.** using [sql
fee0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
fef0: 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
ff00: 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
ff10: 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
ff20: 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
ff30: 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
ff40: 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 53 51  rwise an .** [SQ
ff50: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72  LITE_ERROR | err
ff60: 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
ff70: 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
ff80: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
ff90: 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
ffa0: 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
ffb0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
ffc0: 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
ffd0: 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
ffe0: 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
fff0: 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
10000 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
10010 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
10020 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
10030 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
10040 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68  uraged..** In th
10050 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
10060 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
10070 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
10080 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
10090 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
100a0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
100b0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
100c0 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51   .** original SQ
100d0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
100e0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
100f0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
10100 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
10110 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  a differently in
10120 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a   two ways:.**.**
10130 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
10140 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
10150 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
10160 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
10170 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
10180 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
10190 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
101a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
101b0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
101c0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
101d0 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
101e0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
101f0 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49  run it again.  I
10200 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
10210 20 63 68 61 6e 67 65 64 20 69 6e 20 61 20 77 61   changed in a wa
10220 79 0a 2a 2a 20 74 68 61 74 20 6d 61 6b 65 73 20  y.** that makes 
10230 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
10240 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
10250 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
10260 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
10270 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
10280 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
10290 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
102a0 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
102b0 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
102c0 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
102d0 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
102e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
102f0 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
10300 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
10310 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
10320 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
10330 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
10340 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20  the text of the 
10350 70 61 72 73 69 6e 67 0a 2a 2a 20 65 72 72 6f 72  parsing.** error
10360 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
10370 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
10380 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c  MA] return..** <
10390 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
103a0 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  ** When an error
103b0 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71   occurs, .** [sq
103c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
103d0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
103e0 20 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a   the detailed .*
103f0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  * [SQLITE_ERROR 
10400 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  | result codes] 
10410 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
10420 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
10430 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
10440 5d 20 73 75 63 68 20 61 73 20 64 69 72 65 63 74  ] such as direct
10450 6c 79 2e 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63  ly..** The legac
10460 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
10470 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  hat [sqlite3_ste
10480 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
10490 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
104a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
104b0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61  R] result code a
104c0 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76  nd you would hav
104d0 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
104e0 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nd call to.** [s
104f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
10500 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
10510 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
10520 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
10530 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  blem..** With th
10540 65 20 22 76 32 22 20 70 72 65 70 61 72 65 20 69  e "v2" prepare i
10550 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
10560 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
10570 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
10580 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d  s.** returned im
10590 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
105a0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
105b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
105c0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
105d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
105e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
105f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
10600 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
10610 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
10620 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
10630 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
10640 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
10650 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
10660 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
10670 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
10680 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
10690 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
106a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
106b0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
106c0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
106d0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
106e0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
106f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
10700 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
10710 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
10720 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
10730 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
10740 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
10750 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
10760 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
10770 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
10780 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
10790 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
107a0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
107b0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
107c0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
107d0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
107e0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
107f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
10800 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
10810 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
10820 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
10830 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
10840 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
10850 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
10860 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
10870 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
10880 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
10890 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
108a0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
108b0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
108c0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
108d0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
108e0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
108f0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
10900 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
10910 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
10920 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
10930 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
10940 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
10950 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
10960 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
10970 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
10980 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
10990 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
109a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
109b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
109c0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
109d0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
109e0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
109f0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
10a00 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
10a10 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
10a20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
10a30 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
10a40 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
10a50 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
10a60 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
10a70 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
10a80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
10a90 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
10aa0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
10ab0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
10ac0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
10ad0 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69  API3REF:  Dynami
10ae0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
10af0 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 53  e Object.**.** S
10b00 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
10b10 69 63 20 74 79 70 69 6e 67 20 66 6f 72 20 74 68  ic typing for th
10b20 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
10b30 65 73 2e 20 20 56 61 6c 75 65 73 20 63 61 6e 20  es.  Values can 
10b40 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c  .** be integers,
10b50 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
10b60 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
10b70 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
10b80 20 20 57 68 65 6e 0a 2a 2a 20 70 61 73 73 69 6e    When.** passin
10b90 67 20 61 72 6f 75 6e 64 20 76 61 6c 75 65 73 20  g around values 
10ba0 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 65 61 63 68  internally, each
10bb0 20 76 61 6c 75 65 20 69 73 20 72 65 70 72 65 73   value is repres
10bc0 65 6e 74 65 64 20 61 73 0a 2a 2a 20 61 6e 20 69  ented as.** an i
10bd0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
10be0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
10bf0 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
10c00 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
10c10 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
10c20 20 43 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20   CAPI3REF:  SQL 
10c30 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
10c40 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
10c50 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
10c60 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
10c70 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
10c80 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
10c90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
10ca0 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65  bject.  A pointe
10cb0 72 20 74 6f 20 73 75 63 68 20 61 6e 20 6f 62 6a  r to such an obj
10cc0 65 63 74 20 69 73 20 74 68 65 0a 2a 2a 20 66 69  ect is the.** fi
10cd0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
10ce0 20 75 73 65 72 2d 64 65 66 69 6e 65 64 20 53 51   user-defined SQ
10cf0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a  L functions..*/.
10d00 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
10d10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
10d20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
10d30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10d40 20 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73    Binding Values
10d50 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
10d60 74 65 6d 65 6e 74 73 0a 2a 2a 0a 2a 2a 20 49 6e  tements.**.** In
10d70 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73   the SQL strings
10d80 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
10d90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
10da0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
10db0 73 2c 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  s,.** one or mor
10dc0 65 20 6c 69 74 65 72 61 6c 73 20 63 61 6e 20 62  e literals can b
10dd0 65 20 72 65 70 6c 61 63 65 20 62 79 20 61 20 70  e replace by a p
10de0 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20  arameter in one 
10df0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 66 6f 72 6d  of these.** form
10e00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
10e10 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
10e20 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
10e30 3a 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41  :AAA.** <li>  @A
10e40 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  AA.** <li>  $VVV
10e50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
10e60 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  In the parameter
10e70 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f   forms shown abo
10e80 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74  ve NNN is an int
10e90 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
10ea0 20 41 41 41 20 69 73 20 61 6e 20 61 6c 70 68 61   AAA is an alpha
10eb0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
10ec0 65 72 20 61 6e 64 20 56 56 56 20 69 73 20 61 20  er and VVV is a 
10ed0 76 61 72 69 61 62 6c 65 20 6e 61 6d 65 20 61 63  variable name ac
10ee0 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  cording.** to th
10ef0 65 20 73 79 6e 74 61 78 20 72 75 6c 65 73 20 6f  e syntax rules o
10f00 66 20 74 68 65 20 54 43 4c 20 70 72 6f 67 72 61  f the TCL progra
10f10 6d 6d 69 6e 67 20 6c 61 6e 67 75 61 67 65 2e 0a  mming language..
10f20 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66  ** The values of
10f30 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
10f40 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
10f50 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
10f60 61 6d 65 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ames").** can be
10f70 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
10f80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
10f90 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
10fa0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
10fb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10fc0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
10fd0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
10fe0 20 61 6c 77 61 79 73 20 69 73 20 61 20 70 6f 69   always is a poi
10ff0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
11000 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
11010 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
11020 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
11030 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
11040 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 54  its variants.  T
11050 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
11060 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
11070 65 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  ex of the parame
11080 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 20  ter to be set.  
11090 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
110a0 74 65 72 20 68 61 73 0a 2a 2a 20 61 6e 20 69 6e  ter has.** an in
110b0 64 65 78 20 6f 66 20 31 2e 20 57 68 65 6e 20 74  dex of 1. When t
110c0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 20 70 61  he same named pa
110d0 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
110e0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
110f0 73 65 63 6f 6e 64 0a 2a 2a 20 61 6e 64 20 73 75  second.** and su
11100 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
11110 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
11120 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
11130 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
11140 6e 63 65 2e 20 20 54 68 65 20 69 6e 64 65 78 20  nce.  The index 
11150 66 6f 72 0a 2a 2a 20 6e 61 6d 65 64 20 70 61 72  for.** named par
11160 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
11170 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
11180 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
11190 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
111a0 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  me()] API if des
111b0 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78  ired.  The index
111c0 20 66 6f 72 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 70   for "?NNN".** p
111d0 61 72 61 6d 65 74 65 73 20 69 73 20 74 68 65 20  arametes is the 
111e0 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
111f0 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d   The NNN value m
11200 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
11210 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65   and the compile
11220 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74  -time.** paramet
11230 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41  er SQLITE_MAX_VA
11240 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64  RIABLE_NUMBER (d
11250 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
11260 39 29 2e 0a 2a 2a 20 53 65 65 20 3c 61 20 68 72  9)..** See <a hr
11270 65 66 3d 22 6c 69 6d 69 74 73 2e 68 74 6d 6c 22  ef="limits.html"
11280 3e 6c 69 6d 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e  >limits.html</a>
11290 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
112a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
112b0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67  ** The third arg
112c0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
112d0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
112e0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
112f0 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72  ** In those.** r
11300 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
11310 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
11320 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
11330 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
11340 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20  bytes.** in the 
11350 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
11360 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
11370 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ue is the number
11380 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
11390 0a 2a 2a 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  .** string, not 
113a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
113b0 61 72 61 63 74 65 72 73 2e 20 20 54 68 65 20 6e  aracters.  The n
113c0 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
113d0 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  s does not inclu
113e0 64 65 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  de the zero-term
113f0 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e  inator at the en
11400 64 20 6f 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  d of strings..**
11410 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
11420 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
11430 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
11440 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
11450 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  s.** number of b
11460 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
11470 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
11480 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ator..**.** The 
11490 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
114a0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
114b0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
114c0 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
114d0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
114e0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
114f0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
11500 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
11510 42 4c 4f 42 20 6f 72 0a 2a 2a 20 74 65 78 74 20  BLOB or.** text 
11520 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
11530 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
11540 74 2e 20 20 49 66 20 74 68 65 20 66 69 66 74 68  t.  If the fifth
11550 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
11560 0a 2a 2a 20 73 70 65 63 69 61 6c 20 76 61 6c 75  .** special valu
11570 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
11580 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 69 62 72  ], then the libr
11590 61 72 79 20 61 73 73 75 6d 65 73 20 74 68 61 74  ary assumes that
115a0 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e   the information
115b0 0a 2a 2a 20 69 73 20 69 6e 20 73 74 61 74 69 63  .** is in static
115c0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
115d0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
115e0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
115f0 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 69 66 74    If the.** fift
11600 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
11610 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
11620 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
11630 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  n SQLite makes i
11640 74 73 0a 2a 2a 20 6f 77 6e 20 70 72 69 76 61 74  ts.** own privat
11650 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
11660 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
11670 62 65 66 6f 72 65 20 74 68 65 20 73 71 6c 69 74  before the sqlit
11680 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 72  e3_bind_*().** r
11690 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
116a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
116b0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
116c0 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
116d0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
116e0 20 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   n that.** is fi
116f0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e  lled with zeros.
11700 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65    A zeroblob use
11710 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
11720 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
11730 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
11740 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20  o hold it size) 
11750 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
11760 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
11770 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
11780 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
11790 61 73 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73  as place-holders
117a0 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
117b0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
117c0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
117d0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
117e0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
117f0 65 6d 65 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20  ement BLOB I/O] 
11800 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
11810 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
11820 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75  _*() routines mu
11830 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74  st be called aft
11840 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
11850 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e  repare_v2()] (an
11860 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  d its variants) 
11870 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
11880 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f  t()] and.** befo
11890 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
118a0 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73  ()]..** Bindings
118b0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
118c0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
118d0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
118e0 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61  e..** Unbound pa
118f0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
11900 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
11910 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
11920 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
11930 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
11940 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72  cess or an error
11950 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74   code if.** anyt
11960 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
11970 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d    [SQLITE_RANGE]
11980 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
11990 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
119a0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
119b0 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45   range.  [SQLITE
119c0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
119d0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61  ned if malloc fa
119e0 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ils..** [SQLITE_
119f0 4d 49 53 55 53 45 5d 20 69 73 20 72 65 74 75 72  MISUSE] is retur
11a00 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75  ned if these rou
11a10 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
11a20 20 6f 6e 20 61 20 76 69 72 74 75 61 6c 0a 2a 2a   on a virtual.**
11a30 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73   machine that is
11a40 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65   the wrong state
11a50 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c   or which has al
11a60 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c  ready been final
11a70 69 7a 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ized..*/.int sql
11a80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
11a90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
11aa0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
11ab0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
11ac0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
11ad0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
11ae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
11af0 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
11b00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
11b10 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
11b20 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
11b30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
11b40 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
11b50 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
11b60 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
11b70 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
11b80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
11b90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
11ba0 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
11bb0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
11bc0 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
11bd0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
11be0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
11bf0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
11c00 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
11c10 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
11c20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
11c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
11c40 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
11c50 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
11c60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
11c70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
11c80 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
11c90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
11ca0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
11cb0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
11cc0 4f 66 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65  Of Host Paramete
11cd0 72 73 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  rs.**.** Return 
11ce0 74 68 65 20 6c 61 72 67 65 73 74 20 68 6f 73 74  the largest host
11cf0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 65 78   parameter index
11d00 20 69 6e 20 74 68 65 20 70 72 65 63 6f 6d 70 69   in the precompi
11d10 6c 65 64 20 73 74 61 74 65 6d 65 6e 74 20 67 69  led statement gi
11d20 76 65 6e 0a 2a 2a 20 61 73 20 74 68 65 20 61 72  ven.** as the ar
11d30 67 75 6d 65 6e 74 2e 20 20 57 68 65 6e 20 74 68  gument.  When th
11d40 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  e host parameter
11d50 73 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72  s are of the for
11d60 6d 73 20 6c 69 6b 65 20 22 3a 41 41 41 22 0a 2a  ms like ":AAA".*
11d70 2a 20 6f 72 20 22 3f 22 2c 20 74 68 65 6e 20 74  * or "?", then t
11d80 68 65 79 20 61 72 65 20 61 73 73 69 67 6e 65 64  hey are assigned
11d90 20 73 65 71 75 65 6e 74 69 61 6c 20 69 6e 63 72   sequential incr
11da0 65 61 73 69 6e 67 20 6e 75 6d 62 65 72 73 20 62  easing numbers b
11db0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 77 69 74 68  eginning.** with
11dc0 20 6f 6e 65 2c 20 73 6f 20 74 68 65 20 76 61 6c   one, so the val
11dd0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
11de0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  he number of par
11df0 61 6d 65 74 65 72 73 2e 20 20 48 6f 77 65 76 65  ameters.  Howeve
11e00 72 0a 2a 2a 20 69 66 20 74 68 65 20 73 61 6d 65  r.** if the same
11e10 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
11e20 6e 61 6d 65 20 69 73 20 75 73 65 64 20 6d 75 6c  name is used mul
11e30 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 65 61 63  tiple times, eac
11e40 68 20 6f 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20  h occurrance.** 
11e50 69 73 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  is given the sam
11e60 65 20 6e 75 6d 62 65 72 2c 20 73 6f 20 74 68 65  e number, so the
11e70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
11e80 69 6e 20 74 68 61 74 20 63 61 73 65 20 69 73 20  in that case is 
11e90 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  the number.** of
11ea0 20 75 6e 69 71 75 65 20 68 6f 73 74 20 70 61 72   unique host par
11eb0 61 6d 65 74 65 72 20 6e 61 6d 65 73 2e 20 20 49  ameter names.  I
11ec0 66 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  f host parameter
11ed0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
11ee0 4e 4e 4e 22 0a 2a 2a 20 61 72 65 20 75 73 65 64  NNN".** are used
11ef0 20 28 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61   (where NNN is a
11f00 6e 20 69 6e 74 65 67 65 72 29 20 74 68 65 6e 20  n integer) then 
11f10 74 68 65 72 65 20 6d 69 67 68 74 20 62 65 20 67  there might be g
11f20 61 70 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6e 75  aps in the.** nu
11f30 6d 62 65 72 69 6e 67 20 61 6e 64 20 74 68 65 20  mbering and the 
11f40 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
11f50 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
11f60 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
11f70 20 74 68 65 0a 2a 2a 20 68 6f 73 74 20 70 61 72   the.** host par
11f80 61 6d 65 74 65 72 20 77 69 74 68 20 74 68 65 20  ameter with the 
11f90 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 76 61  largest index va
11fa0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  lue..**.** The p
11fb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11fc0 74 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 5b 73  t must not be [s
11fd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
11fe0 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 0a 2a 2a 20  | finalized].** 
11ff0 70 72 69 6f 72 20 74 6f 20 74 68 69 73 20 72 6f  prior to this ro
12000 75 74 69 6e 65 20 72 65 74 75 72 6e 6e 69 6e 67  utine returnning
12010 2e 20 20 4f 74 68 65 72 77 69 73 65 20 74 68 65  .  Otherwise the
12020 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
12030 65 66 69 6e 65 64 0a 2a 2a 20 61 6e 64 20 70 72  efined.** and pr
12040 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
12050 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  le..*/.int sqlit
12060 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
12070 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
12080 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
12090 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
120a0 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
120b0 72 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  r.**.** This rou
120c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
120d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61  ointer to the na
120e0 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 20 70  me of the n-th p
120f0 61 72 61 6d 65 74 65 72 20 69 6e 20 61 20 0a 2a  arameter in a .*
12100 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
12110 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
12120 6d 65 6e 74 5d 2e 0a 2a 2a 20 48 6f 73 74 20 70  ment]..** Host p
12130 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
12140 20 66 6f 72 6d 20 22 3a 41 41 41 22 20 6f 72 20   form ":AAA" or 
12150 22 40 41 41 41 22 20 6f 72 20 22 24 56 56 56 22  "@AAA" or "$VVV"
12160 20 68 61 76 65 20 61 20 6e 61 6d 65 0a 2a 2a 20   have a name.** 
12170 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
12180 69 6e 67 20 22 3a 41 41 41 22 20 6f 72 20 22 40  ing ":AAA" or "@
12190 41 41 41 22 20 6f 72 20 22 24 56 56 56 22 2e 20  AAA" or "$VVV". 
121a0 20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f   .** In other wo
121b0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
121c0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
121d0 40 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  @".** is include
121e0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
121f0 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65   name..** Parame
12200 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
12210 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 68   "?" or "?NNN" h
12220 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a  ave no name..**.
12230 2a 2a 20 54 68 65 20 66 69 72 73 74 20 62 6f 75  ** The first bou
12240 6e 64 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  nd parameter has
12250 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
12260 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  not 0..**.** If 
12270 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f  the value n is o
12280 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
12290 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d  f the n-th param
122a0 65 74 65 72 20 69 73 20 6e 61 6d 65 6c 65 73 73  eter is nameless
122b0 2c 0a 2a 2a 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ,.** then NULL i
122c0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
122d0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
122e0 20 69 73 20 61 6c 77 61 79 73 20 69 6e 20 74 68   is always in th
122f0 65 0a 2a 2a 20 55 54 46 2d 38 20 65 6e 63 6f 64  e.** UTF-8 encod
12300 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
12310 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
12320 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  was originally s
12330 70 65 63 69 66 69 65 64 0a 2a 2a 20 61 73 20 55  pecified.** as U
12340 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
12350 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
12360 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
12370 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63  re16_v2()]..*/.c
12380 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
12390 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
123a0 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
123b0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
123c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
123d0 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
123e0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
123f0 61 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ame.**.** This r
12400 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
12410 68 65 20 69 6e 64 65 78 20 6f 66 20 61 20 68 6f  he index of a ho
12420 73 74 20 70 61 72 61 6d 65 74 65 72 20 77 69 74  st parameter wit
12430 68 20 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65  h the given name
12440 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6d 75  ..** The name mu
12450 73 74 20 6d 61 74 63 68 20 65 78 61 63 74 6c 79  st match exactly
12460 2e 20 20 49 66 20 6e 6f 20 70 61 72 61 6d 65 74  .  If no paramet
12470 65 72 20 77 69 74 68 20 74 68 65 20 67 69 76 65  er with the give
12480 6e 20 6e 61 6d 65 20 69 73 20 0a 2a 2a 20 66 6f  n name is .** fo
12490 75 6e 64 2c 20 72 65 74 75 72 6e 20 30 2e 20 20  und, return 0.  
124a0 50 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 20  Parameter names 
124b0 6d 75 73 74 20 62 65 20 55 54 46 38 2e 0a 2a 2f  must be UTF8..*/
124c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
124d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
124e0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
124f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
12500 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
12510 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
12520 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
12530 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
12540 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20  .**.** Contrary 
12550 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
12560 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
12570 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
12580 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68   not.** reset th
12590 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
125a0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
125b0 20 6f 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74   on a .** [sqlit
125c0 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
125d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
125e0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
125f0 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c   to.** reset all
12600 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
12610 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
12620 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
12630 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
12640 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
12650 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
12660 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
12670 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
12680 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62   Return the numb
12690 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
126a0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
126b0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
126c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
126d0 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  t | compiled SQL
126e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69   statement]. Thi
126f0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
12700 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74 20  s 0.** if pStmt 
12710 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  is an SQL statem
12720 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
12730 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
12740 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 61  or .** example a
12750 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2f 0a 69 6e  n UPDATE)..*/.in
12760 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
12770 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
12780 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
12790 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
127a0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
127b0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
127c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
127d0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
127e0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
127f0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
12800 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
12810 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54   set of a SELECT
12820 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65   statement.  The
12830 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
12840 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
12850 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
12860 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 38 20  inter to a UTF8 
12870 73 74 72 69 6e 67 20 61 6e 64 20 73 71 6c 69 74  string and sqlit
12880 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
12890 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
128a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46  pointer to a UTF
128b0 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
128c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
128d0 69 73 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  is the.** [sqlit
128e0 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
128f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
12900 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
12910 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  e SELECT stateme
12920 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  nt..** The secon
12930 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
12940 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  he column number
12950 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  .  The left-most
12960 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75   column is.** nu
12970 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68  mber 0..**.** Th
12980 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
12990 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
129a0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
129b0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
129c0 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
129d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
129e0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
129f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
12a00 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
12a10 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74   next call sqlit
12a20 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
12a30 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
12a40 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f  mn_name16().** o
12a50 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
12a60 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69  n..**.** If sqli
12a70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
12a80 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
12a90 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
12aa0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
12ab0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
12ac0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
12ad0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
12ae0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
12af0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
12b00 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  eturned..*/.cons
12b10 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
12b20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
12b30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
12b40 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
12b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
12b60 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
12b70 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
12b80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
12b90 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
12ba0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
12bb0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
12bc0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
12bd0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
12be0 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77  what column of w
12bf0 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20  hat.** table in 
12c00 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61  which database a
12c10 20 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c   result of a SEL
12c20 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ECT statement co
12c30 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65  mes from..** The
12c40 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
12c50 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
12c60 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
12c70 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
12c80 69 74 68 65 72 20 61 20 55 54 46 38 20 6f 72 20  ither a UTF8 or 
12c90 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54  UTF16 string.  T
12ca0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
12cb0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
12cc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
12cd0 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
12ce0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
12cf0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
12d00 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
12d10 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
12d20 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
12d30 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  me..** The retur
12d40 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
12d50 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65  lid until.** the
12d60 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
12d70 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
12d80 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
12d90 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
12da0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
12db0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
12dc0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
12dd0 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
12de0 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
12df0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
12e00 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74  ** The names ret
12e10 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
12e20 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
12e30 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
12e40 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
12e50 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
12e60 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
12e70 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66  rgument to the f
12e80 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69  ollowing calls i
12e90 73 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s a .** [sqlite3
12ea0 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
12eb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e   SQL statement].
12ec0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
12ed0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
12ee0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
12ef0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
12f00 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68 65 20  rned by .** the 
12f10 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
12f20 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
12f30 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
12f40 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  nt..**.** If the
12f50 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
12f60 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
12f70 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
12f80 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62  ession.** or sub
12f90 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
12fa0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
12fb0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
12fc0 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  se functions.** 
12fd0 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 4f 74 68  return NULL. Oth
12fe0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
12ff0 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65  urn the .** name
13000 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
13010 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
13020 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74   and column that
13030 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
13040 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
13050 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
13060 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74  * As with all ot
13070 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
13080 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64   those postfixed
13090 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
130a0 6e 20 55 54 46 2d 31 36 0a 2a 2a 20 65 6e 63 6f  n UTF-16.** enco
130b0 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65  ded strings, the
130c0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
130d0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
130e0 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20  *.** These APIs 
130f0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
13100 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
13110 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
13120 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
13130 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
13140 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f  _METADATA prepro
13150 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
13160 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
13170 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
13180 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
13190 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
131a0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
131b0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
131c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
131d0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
131e0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
131f0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
13200 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  * undefined..*/.
13210 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
13220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
13230 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
13240 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
13250 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
13260 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
13270 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
13280 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
13290 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
132a0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
132b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
132c0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
132d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
132e0 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
132f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
13300 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
13310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
13320 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
13330 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
13340 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
13350 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
13360 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
13370 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
13380 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
13390 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
133a0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
133b0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
133c0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 73  arameter is a [s
133d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f  qlite3_stmt | co
133e0 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
133f0 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68  ment]. .** If th
13400 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
13410 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
13420 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
13430 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a  olumn of the .**
13440 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
13450 20 73 65 74 20 20 6f 66 20 74 68 61 74 20 53 45   set  of that SE
13460 4c 45 43 54 20 69 73 20 61 20 74 61 62 6c 65 20  LECT is a table 
13470 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
13480 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
13490 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
134a0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
134b0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
134c0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
134d0 6e 65 64 2e 20 49 66 20 74 68 65 20 4e 74 68 20  ned. If the Nth 
134e0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
134f0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
13500 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
13510 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
13520 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
13530 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68   returned..** Th
13540 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
13550 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
13560 38 20 65 6e 63 6f 64 65 64 2e 20 46 6f 72 20 65  8 encoded. For e
13570 78 61 6d 70 6c 65 2c 20 69 6e 0a 2a 2a 20 74 68  xample, in.** th
13580 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
13590 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
135a0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
135b0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20  ANT);.**.** And 
135c0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
135d0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64  atement compiled
135e0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
135f0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
13600 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68  1;.**.** Then th
13610 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
13620 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
13630 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
13640 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72   the second.** r
13650 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
13660 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
13670 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
13680 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
13690 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a  umn.** (i==0)..*
136a0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
136b0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
136c0 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75  e typing.  So ju
136d0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
136e0 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
136f0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
13700 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
13710 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
13720 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
13730 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
13740 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
13750 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
13760 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
13770 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
13780 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
13790 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
137a0 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73  .  Type.** is as
137b0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
137c0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
137d0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
137e0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
137f0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
13800 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
13810 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
13820 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
13830 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2c 20 69 6e  lite3_stmt *, in
13840 74 20 69 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t i);.const void
13850 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
13860 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
13870 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
13880 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45 46  ./* .** CAPI3REF
13890 3a 20 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  :  Evaluate An S
138a0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
138b0 2a 2a 20 41 66 74 65 72 20 61 6e 20 5b 73 71 6c  ** After an [sql
138c0 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
138d0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
138e0 65 65 6e 20 70 72 65 70 61 72 65 64 20 77 69 74  een prepared wit
138f0 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65  h a call.** to e
13900 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
13910 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
13920 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
13930 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f  16_v2()] or to o
13940 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67  ne of.** the leg
13950 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b  acy interfaces [
13960 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
13970 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
13980 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20  repare16()],.** 
13990 74 68 65 6e 20 74 68 69 73 20 66 75 6e 63 74 69  then this functi
139a0 6f 6e 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  on must be calle
139b0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
139c0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
139d0 74 68 65 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  the .** statemen
139e0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
139f0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
13a00 76 69 6f 72 20 6f 66 20 74 68 69 73 20 73 71 6c  vior of this sql
13a10 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
13a20 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
13a30 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
13a40 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
13a50 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
13a60 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
13a70 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
13a80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
13a90 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
13aa0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
13ab0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
13ac0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
13ad0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
13ae0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
13af0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
13b00 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
13b10 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
13b20 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
13b30 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
13b40 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
13b50 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
13b60 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
13b70 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
13b80 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 61  .**.** In the la
13b90 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
13ba0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
13bb0 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
13bc0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a  [SQLITE_BUSY], .
13bd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
13be0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
13bf0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
13c00 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
13c10 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  E]..** With the 
13c20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
13c30 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
13c40 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
13c50 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72  sult code].** or
13c60 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
13c70 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
13c80 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68  esult code] migh
13c90 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
13ca0 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  .** well..**.** 
13cb0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
13cc0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
13cd0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
13ce0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
13cf0 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
13d00 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
13d10 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
13d20 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
13d30 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a  nt is a COMMIT.*
13d40 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
13d50 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
13d60 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
13d70 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
13d80 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
13d90 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
13da0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
13db0 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75 72  COMMIT and occur
13dc0 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78  s within a.** ex
13dd0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
13de0 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
13df0 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
13e00 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
13e10 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
13e20 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
13e30 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
13e40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
13e50 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
13e60 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
13e70 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
13e80 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
13e90 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
13ea0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
13eb0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
13ec0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
13ed0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
13ee0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
13ef0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
13f00 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
13f10 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
13f20 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
13f30 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
13f40 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
13f50 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
13f60 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57   .** [SQLITE_ROW
13f70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  ] is returned ea
13f80 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
13f90 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
13fa0 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73  dy.** for proces
13fb0 73 69 6e 67 20 62 79 20 74 68 65 20 63 61 6c 6c  sing by the call
13fc0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
13fd0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
13fe0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
13ff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
14000 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20  | column access 
14010 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
14020 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
14030 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
14040 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
14050 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
14060 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  ** .** [SQLITE_E
14070 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
14080 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
14090 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
140a0 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
140b0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
140c0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
140d0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
140e0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
140f0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
14100 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
14110 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
14120 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
14130 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74  rrmsg()]..** Wit
14140 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
14150 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
14160 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
14170 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20  de (example:.** 
14180 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
14190 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
141a0 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
141b0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
141c0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
141d0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
141e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
141f0 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
14200 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
14210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
14220 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22  t].  In the "v2"
14230 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
14240 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
14250 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
14260 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
14270 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
14280 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
14290 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
142a0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
142b0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
142c0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
142d0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
142e0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
142f0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
14300 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14310 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
14320 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
14330 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
14340 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
14350 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a  n one that had .
14360 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
14370 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
14380 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
14390 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
143a0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
143b0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
143c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
143d0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
143e0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
143f0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
14400 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
14410 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
14420 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
14430 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a  ce Alert:</b>.**
14440 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
14450 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68  nterface, .** th
14460 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
14470 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
14480 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
14490 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51  ror code,.** [SQ
144a0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
144b0 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72  lowing any error
144c0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
144d0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64  ITE_BUSY].** and
144e0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
144f0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
14500 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
14510 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
14520 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
14530 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
14540 6e 65 20 6f 66 20 74 68 65 20 73 70 65 63 69 66  ne of the specif
14550 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  ic.** [SQLITE_ER
14560 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ROR | result cod
14570 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
14580 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
14590 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
145a0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
145b0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
145c0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
145d0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
145e0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
145f0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
14600 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
14610 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
14620 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
14630 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
14640 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
14650 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
14660 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
14670 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
14680 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
14690 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
146a0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e  epare16()], then
146b0 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70   the .** more sp
146c0 65 63 69 66 69 63 20 5b 53 51 4c 49 54 45 5f 45  ecific [SQLITE_E
146d0 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f  RROR | result co
146e0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
146f0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
14700 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
14710 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
14720 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
14730 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
14740 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
14750 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
14760 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
14770 52 45 46 3a 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  REF:.**.** Retur
14780 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
14790 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75  values in the cu
147a0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
147b0 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a   result set..**.
147c0 2a 2a 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20  ** After a call 
147d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
147e0 28 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73  ()] that returns
147f0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
14800 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77  his routine.** w
14810 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73  ill return the s
14820 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74 68 65  ame value as the
14830 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
14840 5f 63 6f 75 6e 74 28 29 5d 20 66 75 6e 63 74 69  _count()] functi
14850 6f 6e 2e 0a 2a 2a 20 41 66 74 65 72 20 5b 73 71  on..** After [sq
14860 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
14870 73 20 72 65 74 75 72 6e 65 64 20 61 6e 20 5b 53  s returned an [S
14880 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
14890 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 0a 2a  LITE_BUSY], or.*
148a0 2a 20 61 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  * a [SQLITE_ERRO
148b0 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 2c  R | error code],
148c0 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69   or before [sqli
148d0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
148e0 62 65 65 6e 20 0a 2a 2a 20 63 61 6c 6c 65 64 20  been .** called 
148f0 6f 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  on the [sqlite3_
14900 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
14910 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74  statement] for t
14920 68 65 20 66 69 72 73 74 20 74 69 6d 65 2c 0a 2a  he first time,.*
14930 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * this routine r
14940 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a  eturns zero..*/.
14950 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
14960 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
14970 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
14980 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
14990 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
149a0 70 65 73 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  pes.**.** Every 
149b0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
149c0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
149d0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
149e0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
149f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
14a00 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
14a10 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
14a20 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
14a30 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
14a40 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
14a50 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
14a60 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  LL.** </ul>.**.*
14a70 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
14a80 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
14a90 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
14aa0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
14ab0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
14ac0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
14ad0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
14ae0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
14af0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
14b00 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
14b10 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
14b20 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
14b30 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
14b40 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
14b50 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
14b60 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
14b70 49 54 45 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a  ITE3_TEXT not.**
14b80 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
14b90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14ba0 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
14bb0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
14bc0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
14bd0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
14be0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
14bf0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
14c00 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
14c10 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
14c20 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
14c30 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
14c40 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
14c50 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
14c60 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
14c70 45 46 3a 20 52 65 73 75 6c 74 73 20 56 61 6c 75  EF: Results Valu
14c80 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
14c90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
14ca0 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
14cb0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a  rmation about.**
14cc0 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
14cd0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
14ce0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
14cf0 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79  query.  In every
14d00 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 66 69 72  .** case the fir
14d10 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
14d20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
14d30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
14d40 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  t | SQL statemen
14d50 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
14d60 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28 74  .** evaluated (t
14d70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
14d80 2a 5d 20 74 68 61 74 20 77 61 73 20 72 65 74 75  *] that was retu
14d90 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  rned from .** [s
14da0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
14db0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
14dc0 74 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e 64  ts variants) and
14dd0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61  .** the second a
14de0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
14df0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
14e00 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
14e10 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f  ormation .** sho
14e20 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
14e30 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20    The left-most 
14e40 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
14e50 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 20  sult set.** has 
14e60 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a  an index of 0..*
14e70 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
14e80 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
14e90 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
14ea0 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
14eb0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 68   or if the.** th
14ec0 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  e column index i
14ed0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
14ee0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
14ef0 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65  defined. .** The
14f00 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
14f10 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
14f20 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
14f30 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
14f40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
14f50 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
14f60 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
14f70 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
14f80 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
14f90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
14fa0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
14fb0 6c 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  l subsequently..
14fc0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
14fd0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
14fe0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
14ff0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
15000 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
15010 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
15020 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
15030 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
15040 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
15050 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
15060 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
15070 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
15080 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
15090 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
150a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
150b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
150c0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
150d0 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
150e0 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
150f0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
15100 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
15110 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
15120 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
15130 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20  efined.  .**.** 
15140 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
15150 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
15160 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  e returns .** [S
15170 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
15180 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
15190 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
151a0 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
151b0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
151c0 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
151d0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
151e0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
151f0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
15200 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
15210 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
15220 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
15230 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
15240 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
15250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
15260 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
15270 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
15280 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
15290 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
152a0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
152b0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
152c0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
152d0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
152e0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
152f0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
15300 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
15310 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
15320 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
15330 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
15340 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
15350 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
15360 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
15370 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
15380 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
15390 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
153a0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
153b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
153c0 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74  bytes() .** rout
153d0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
153e0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
153f0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
15400 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68  string..** If th
15410 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
15420 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
15430 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
15440 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
15450 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
15460 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
15470 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
15480 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
15490 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
154a0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
154b0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
154c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
154d0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
154e0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
154f0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
15500 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
15510 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
15520 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
15530 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
15540 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61  tring..** The va
15550 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65  lue returned doe
15560 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  s not include th
15570 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
15580 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  r at the end.** 
15590 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
155a0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
155b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
155c0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
155d0 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
155e0 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
155f0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
15600 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cters..**.** The
15610 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
15620 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
15630 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
15640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
15650 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
15660 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
15670 69 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 65 61  in UTF-16 instea
15680 64 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a  d of UTF-8.  .**
15690 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   The zero termin
156a0 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c  ator is not incl
156b0 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75  uded in this cou
156c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  nt..**.** These 
156d0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
156e0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
156f0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
15700 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a  opriate.  For.**
15710 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
15720 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
15730 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
15740 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
15750 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
15760 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
15770 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
15780 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
15790 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  do the conversio
157a0 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  n.** automatical
157b0 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ly.  The followi
157c0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
157d0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
157e0 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70   that.** are app
157f0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
15800 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
15810 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
15820 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
15830 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
15840 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
15850 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
15860 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
15870 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
15880 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
15890 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
158a0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
158b0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
158c0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
158d0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
158e0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
158f0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
15900 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
15910 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
15920 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
15930 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
15940 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
15950 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
15960 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
15970 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
15980 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
15990 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
159a0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
159b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
159c0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
159d0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
159e0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
159f0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
15a00 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
15a10 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e  as for INTEGER->
15a20 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
15a30 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
15a40 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
15a50 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
15a60 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
15a70 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
15a80 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
15a90 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
15aa0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
15ab0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
15ac0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
15ad0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
15ae0 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
15af0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
15b00 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
15b10 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
15b20 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
15b30 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
15b40 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
15b50 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
15b60 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
15b70 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
15b80 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
15b90 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
15ba0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
15bb0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
15bc0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
15bd0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
15be0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
15bf0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
15c00 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
15c10 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
15c20 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
15c30 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
15c40 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
15c50 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
15c60 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
15c70 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
15c80 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
15c90 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
15ca0 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
15cb0 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
15cc0 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
15cd0 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
15ce0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
15cf0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
15d00 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
15d10 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75  as its.** on equ
15d20 61 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  avalent internal
15d30 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
15d40 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
15d50 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
15d60 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
15d70 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
15d80 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
15d90 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
15da0 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
15db0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
15dc0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
15dd0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
15de0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
15df0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
15e00 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
15e10 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
15e20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
15e30 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
15e40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
15e50 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
15e60 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a  invalidated. .**
15e70 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
15e80 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
15e90 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
15ea0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
15eb0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
15ec0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
15ed0 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
15ee0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
15ef0 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
15f00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
15f10 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ) .**          o
15f20 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
15f30 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
15f40 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
15f50 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
15f60 20 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74            need t
15f70 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
15f80 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c  e string.</p></l
15f90 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e  i>.**.** <li><p>
15fa0 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
15fb0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
15fc0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
15fd0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
15fe0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
15ff0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
16000 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
16010 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
16020 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
16030 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  d.**          to
16040 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69   UTF-16.</p></li
16050 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  >.**.** <li><p> 
16060 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
16070 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
16080 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
16090 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
160a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71  r.**          sq
160b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
160c0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
160d0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
160e0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
160f0 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46            to UTF
16100 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20  -8.</p></li>.** 
16110 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76  </ul>.**.** Conv
16120 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
16130 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
16140 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
16150 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
16160 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
16170 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
16180 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
16190 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
161a0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
161b0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
161c0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
161d0 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
161e0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
161f0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
16200 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
16210 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
16220 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
16230 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
16240 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  me it is.** not 
16250 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
16260 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
16270 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
16280 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a  nvalidated.  .**
16290 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
162a0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
162b0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
162c0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
162d0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
162e0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
162f0 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
16300 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73    <ul>.**  <li>s
16310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
16320 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
16330 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
16340 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
16350 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
16360 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
16370 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
16380 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
16390 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
163a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
163b0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
163c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
163d0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
163e0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
163f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
16400 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
16410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
16420 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
16430 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72  mn_blob(),.** or
16440 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
16450 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
16460 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
16470 6c 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  lt into the desi
16480 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74  red.** format, t
16490 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
164a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
164b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
164c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
164d0 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a  .** find the siz
164e0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
164f0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
16500 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  l to sqlite3_col
16510 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
16520 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
16530 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
16540 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
16550 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20  umn_bytes16().  
16560 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69  And do not.** mi
16570 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
16580 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
16590 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
165a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
165b0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  bytes()..**.** T
165c0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
165d0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
165e0 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
165f0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
16600 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
16610 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
16620 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
16630 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
16640 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
16650 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
16660 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d  s called.  The m
16670 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
16680 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
16690 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73  .** and blobs is
166a0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
166b0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
166c0 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
166d0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
166e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
166f0 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
16700 69 74 65 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  ite_column_text(
16710 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a  )], etc. into .*
16720 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
16730 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d  )]..**.** If a m
16740 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16750 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
16760 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
16770 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
16780 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
16790 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
167a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
167b0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
167c0 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
167d0 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
167e0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
167f0 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
16800 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
16810 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
16820 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
16830 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
16840 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
16850 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e  E_NOMEM]..*/.con
16860 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
16870 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
16880 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
16890 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
168a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
168b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
168c0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
168d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
168e0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
168f0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
16900 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
16910 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
16920 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
16930 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
16940 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
16950 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
16960 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
16970 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
16980 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
16990 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
169a0 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
169b0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
169c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
169d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
169e0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
169f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
16a00 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
16a10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
16a20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
16a30 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
16a40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
16a50 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
16a60 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
16a70 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
16a80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
16a90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16aa0 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
16ab0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
16ac0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
16ad0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
16ae0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
16af0 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
16b00 65 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e a .** [sqlite3
16b10 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
16b20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e   SQL statement].
16b30 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
16b40 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74 65  t was.** execute
16b50 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  d successfully, 
16b60 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
16b70 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c  at all, then SQL
16b80 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
16b90 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75 74  ed..** If execut
16ba0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
16bb0 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
16bc0 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   an .** [SQLITE_
16bd0 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f  ERROR | error co
16be0 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  de] or [SQLITE_I
16bf0 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
16c00 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
16c10 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e  .** is returned.
16c20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75   .**.** This rou
16c30 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
16c40 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
16c50 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75  during the execu
16c60 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  tion of the.** [
16c70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 76  sqlite3_stmt | v
16c80 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 5d 2e  irtual machine].
16c90 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c    If the virtual
16ca0 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74   machine has not
16cb0 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65   .** completed e
16cc0 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68  xecution when th
16cd0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  is routine is ca
16ce0 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69  lled, that is li
16cf0 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69  ke.** encounteri
16d00 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61  ng an error or a
16d10 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20 28 53  n interrupt.  (S
16d20 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  ee [sqlite3_inte
16d30 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a 20 49  rrupt()].) .** I
16d40 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65  ncomplete update
16d50 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20  s may be rolled 
16d60 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63  back and transac
16d70 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65 64 2c  tions cancelled,
16d80 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20    .** depending 
16d90 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61  on the circumsta
16da0 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20 0a 2a  nces, and the .*
16db0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  * [SQLITE_ERROR 
16dc0 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 72  | result code] r
16dd0 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
16de0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
16df0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
16e00 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
16e10 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
16e20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
16e30 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
16e40 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
16e50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
16e60 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
16e70 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
16e80 20 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 73 71   reset a .** [sq
16e90 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d  lite3_stmt | com
16ea0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
16eb0 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  ent] object..** 
16ec0 62 61 63 6b 20 74 6f 20 69 74 27 73 20 69 6e 69  back to it's ini
16ed0 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
16ee0 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
16ef0 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20  ted..** Any SQL 
16f00 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
16f10 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
16f20 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
16f30 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
16f40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
16f50 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
16f60 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
16f70 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
16f80 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
16f90 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
16fa0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
16fb0 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 69 6e 74 20 73  ndings..*/.int s
16fc0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
16fd0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
16fe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16ff0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
17000 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
17010 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ions.**.** The f
17020 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
17030 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20  ctions are used 
17040 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
17050 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
17060 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65  es.** or to rede
17070 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
17080 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  r of existing SQ
17090 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
170a0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a  ggregates.  The.
170b0 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e  ** difference on
170c0 6c 79 20 62 65 74 77 65 65 6e 20 74 68 65 20 74  ly between the t
170d0 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
170e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
170f0 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20   the.** name of 
17100 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e  the (scalar) fun
17110 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
17120 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
17130 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  n UTF-8 for.** s
17140 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
17150 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46  nction() and UTF
17160 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  -16 for sqlite3_
17170 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
17180 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  6()..**.** The f
17190 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
171a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 20 7c 20   the [sqlite3 | 
171b0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d  database handle]
171c0 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 0a   that holds the.
171d0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
171e0 6f 72 20 61 67 67 72 65 67 61 74 65 20 69 73 20  or aggregate is 
171f0 74 6f 20 62 65 20 61 64 64 65 64 20 6f 72 20 72  to be added or r
17200 65 64 65 66 69 6e 65 64 2e 20 49 66 20 61 20 73  edefined. If a s
17210 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  ingle.** program
17220 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
17230 6f 6e 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  one database han
17240 64 6c 65 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20  dle internally, 
17250 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63  then SQL.** func
17260 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
17270 74 65 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  tes must be adde
17280 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74  d individually t
17290 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a  o each database.
172a0 2a 2a 20 68 61 6e 64 6c 65 20 77 69 74 68 20 77  ** handle with w
172b0 68 69 63 68 20 74 68 65 79 20 77 69 6c 6c 20 62  hich they will b
172c0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
172d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
172e0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
172f0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
17300 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
17310 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64  .** or redefined
17320 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20  ..** The length 
17330 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
17340 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
17350 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  tes, exclusive o
17360 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74  f the .** zero-t
17370 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65  erminator.  Note
17380 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c   that the name l
17390 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
173a0 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20  n bytes, not.** 
173b0 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79  characters.  Any
173c0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
173d0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
173e0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
173f0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
17400 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52  in an SQLITE_ERR
17410 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  OR error..**.** 
17420 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
17430 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ter is the numbe
17440 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
17450 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
17460 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
17470 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74  gate takes. If t
17480 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
17490 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
174a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
174b0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
174c0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
174d0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
174e0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  s..**.** The fou
174f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
17500 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
17510 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c  es what .** [SQL
17520 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
17530 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
17540 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
17550 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
17560 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20  arameters.  Any 
17570 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
17580 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
17590 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  ld be able to wo
175a0 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20  rk.** work with 
175b0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
175c0 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
175d0 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
175e0 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
175f0 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
17600 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
17610 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
17620 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20    It is allowed 
17630 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
17640 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
17650 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
17660 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
17670 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
17680 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
17690 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
176a0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
176b0 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
176c0 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75  tRep..** When mu
176d0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
176e0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
176f0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
17700 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
17710 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
17720 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
17730 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
17740 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
17750 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
17760 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
17770 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
17780 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
17790 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a   not care what.*
177a0 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  * text encoding 
177b0 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
177c0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
177d0 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b  t should be.** [
177e0 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
177f0 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72  ** The fifth par
17800 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
17810 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
17820 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
17830 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75  ion.** of the fu
17840 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
17850 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
17860 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20  ointer using.** 
17870 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
17880 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ta()]..**.** The
17890 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
178a0 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
178b0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
178c0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
178d0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
178e0 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
178f0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
17900 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a  lement the SQL.*
17910 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  * function or ag
17920 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61  gregate. A scala
17930 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
17940 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
17950 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mentation of.** 
17960 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61  the xFunc callba
17970 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f  ck only, NULL po
17980 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
17990 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
179a0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
179b0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41  al parameters. A
179c0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
179d0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
179e0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
179f0 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20  ion.** of xStep 
17a00 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
17a10 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ULL should be pa
17a20 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
17a30 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20  To delete an.** 
17a40 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
17a50 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
17a60 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
17a70 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
17a80 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
17a90 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
17aa0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
17ab0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
17ac0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
17ad0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
17ae0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
17af0 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
17b00 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
17b10 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
17b20 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
17b30 66 66 65 72 69 6e 67 20 70 65 72 66 65 72 72 65  ffering perferre
17b40 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
17b50 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
17b60 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
17b70 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
17b80 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
17b90 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
17ba0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
17bb0 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2f 0a 69  on is used..*/.i
17bc0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
17bd0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
17be0 6c 69 74 65 33 20 2a 2c 0a 20 20 63 6f 6e 73 74  lite3 *,.  const
17bf0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
17c00 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
17c10 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
17c20 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69  ,.  void*,.  voi
17c30 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
17c40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
17c50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
17c60 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
17c70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
17c80 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
17c90 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
17ca0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
17cb0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
17cc0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
17cd0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
17ce0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73  sqlite3*,.  cons
17cf0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
17d00 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
17d10 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
17d20 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  p,.  void*,.  vo
17d30 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
17d40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
17d50 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
17d60 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
17d70 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
17d80 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
17d90 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
17da0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
17db0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
17dc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17dd0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
17de0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
17df0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
17e00 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
17e10 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
17e20 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
17e30 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
17e40 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
17e50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
17e60 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
17e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
17e80 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
17e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
17ea0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
17eb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
17ec0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
17ed0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
17ee0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
17ef0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
17f00 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
17f10 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
17f20 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
17f30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17f40 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
17f50 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
17f60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
17f70 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
17f80 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f  * CAPI3REF: Obso
17f90 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  lete Functions.*
17fa0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
17fb0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77  ions are all now
17fc0 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f   obsolete.  In o
17fd0 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
17fe0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
17ff0 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
18000 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20   older code, we 
18010 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70  continue to supp
18020 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  ort.** these fun
18030 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72  ctions.  However
18040 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e  , new developmen
18050 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c  t projects shoul
18060 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
18070 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
18080 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
18090 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
180a0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
180b0 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
180c0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
180d0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
180e0 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a   want they do..*
180f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  /.int sqlite3_ag
18100 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
18110 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
18120 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70  .int sqlite3_exp
18130 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
18140 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
18150 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
18160 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
18170 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
18180 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  ;.int sqlite3_gl
18190 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
181a0 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  d);.void sqlite3
181b0 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
181c0 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
181d0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
181e0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
181f0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
18200 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
18210 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
18220 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
18230 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
18240 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
18250 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
18260 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
18270 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
18280 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
18290 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
182a0 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
182b0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
182c0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
182d0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
182e0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
182f0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
18300 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
18310 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
18320 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
18330 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
18340 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
18350 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
18360 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
18370 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
18380 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
18390 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
183a0 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
183b0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
183c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
183d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
183e0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
183f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
18400 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
18410 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
18420 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
18430 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
18440 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
18450 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
18460 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
18470 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
18480 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
18490 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
184a0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
184b0 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  ding .** [sqlite
184c0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20  3_column_blob | 
184d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
184e0 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63 65 70   routines] excep
184f0 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65 73 65  t that .** these
18500 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
18510 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33   single [sqlite3
18520 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72  _value*] pointer
18530 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
18540 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  n [sqlite3_stmt*
18550 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
18560 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
18570 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  number..**.** Th
18580 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
18590 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
185a0 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
185b0 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  F16 string.** in
185c0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
185d0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
185e0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
185f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
18600 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
18610 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
18620 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
18630 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
18640 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61 73  UTF16 strings as
18650 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
18660 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
18670 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
18680 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
18690 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
186a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
186b0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
186c0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
186d0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
186e0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
186f0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
18700 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
18710 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
18720 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
18730 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
18740 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
18750 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
18760 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
18770 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
18780 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 77 6f 72 64  in order.** word
18790 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  s if the value i
187a0 73 20 6f 72 69 67 69 6e 61 6c 20 61 20 73 74 72  s original a str
187b0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
187c0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
187d0 20 74 68 65 6e 20 69 74 20 69 73 20 64 6f 6e 65   then it is done
187e0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
187f0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
18800 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c  s.  The .** [SQL
18810 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
18820 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
18830 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
18840 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
18850 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
18860 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
18870 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
18880 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
18890 20 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f   is returned fro
188a0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
188b0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
188c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
188d0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
188e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
188f0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
18900 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
18910 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
18920 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
18930 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
18940 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
18950 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
18960 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
18970 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
18980 74 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a  text16()].  .**.
18990 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
189a0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
189b0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
189c0 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
189d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
189e0 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 73  t supplied the s
189f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70 61  qlite3_value* pa
18a00 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c  rameters..** Or,
18a10 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
18a20 76 61 6c 75 65 2a 20 61 72 67 75 6d 65 6e 74 20  value* argument 
18a30 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  comes from the [
18a40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
18a50 61 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  alue()].** inter
18a60 66 61 63 65 2c 20 74 68 65 6e 20 74 68 65 73 65  face, then these
18a70 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
18a80 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
18a90 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 0a  the same thread.
18aa0 2a 2a 20 74 68 61 74 20 72 61 6e 20 5b 73 71 6c  ** that ran [sql
18ab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
18ac0 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  e()]..*/.const v
18ad0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
18ae0 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
18af0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
18b00 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
18b10 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
18b20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
18b30 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
18b40 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
18b50 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
18b60 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
18b70 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
18b80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
18b90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
18ba0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
18bb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
18bc0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
18bd0 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
18be0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
18bf0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
18c00 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
18c10 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
18c20 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
18c30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
18c40 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
18c50 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
18c60 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
18c70 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
18c80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
18c90 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
18ca0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
18cb0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
18cc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
18cd0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
18ce0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
18cf0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
18d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18d10 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
18d20 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
18d30 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  t.**.** The impl
18d40 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
18d50 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
18d60 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
18d70 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
18d80 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
18d90 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
18da0 65 69 72 20 73 74 61 74 65 2e 20 20 54 68 65 20  eir state.  The 
18db0 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
18dc0 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 63 61  routine.** is ca
18dd0 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74 69  lled for a parti
18de0 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
18df0 20 61 20 6e 65 77 20 73 74 72 75 63 74 75 72 65   a new structure
18e00 20 6f 66 20 73 69 7a 65 20 6e 42 79 74 65 73 0a   of size nBytes.
18e10 2a 2a 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 2c  ** is allocated,
18e20 20 7a 65 72 6f 65 64 2c 20 61 6e 64 20 72 65 74   zeroed, and ret
18e30 75 72 6e 65 64 2e 20 20 4f 6e 20 73 75 62 73 65  urned.  On subse
18e40 71 75 65 6e 74 20 63 61 6c 6c 73 20 28 66 6f 72  quent calls (for
18e50 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 61 67 67   the.** same agg
18e60 72 65 67 61 74 65 20 69 6e 73 74 61 6e 63 65 29  regate instance)
18e70 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
18e80 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
18e90 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
18ea0 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72  n.** of the aggr
18eb0 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68  egate can use th
18ec0 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65  e returned buffe
18ed0 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20  r to accumulate 
18ee0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  data..**.** The 
18ef0 62 75 66 66 65 72 20 61 6c 6c 6f 63 61 74 65 64  buffer allocated
18f00 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
18f10 74 69 63 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  tically by SQLit
18f20 65 20 77 68 61 6e 20 74 68 65 20 61 67 67 72 65  e whan the aggre
18f30 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f  gate.** query co
18f40 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
18f50 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
18f60 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  er should be a c
18f70 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b  opy of the .** [
18f80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
18f90 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
18fa0 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
18fb0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
18fc0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
18fd0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
18fe0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
18ff0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
19000 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
19010 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
19020 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
19030 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
19040 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
19050 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
19060 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
19070 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
19080 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
19090 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
190a0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
190b0 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
190c0 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
190d0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
190e0 2a 0a 2a 2a 20 54 68 65 20 70 55 73 65 72 44 61  *.** The pUserDa
190f0 74 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ta parameter to 
19100 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
19110 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
19120 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
19130 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
19140 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  6()] routines.**
19150 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
19160 72 20 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 73  r user functions
19170 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f   is available to
19180 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
19190 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 75  tation of the fu
191a0 6e 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 69  nction using thi
191b0 73 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s call..**.** Th
191c0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
191d0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
191e0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
191f0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
19200 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
19210 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
19220 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
19230 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
19240 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
19250 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
19260 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
19270 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
19280 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
19290 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
192a0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
192b0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
192c0 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77  iate meta-data w
192d0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
192e0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
192f0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
19300 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
19310 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
19320 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
19330 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
19340 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
19350 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
19360 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
19370 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74  ociated meta-dat
19380 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
19390 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
193a0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
193b0 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
193c0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
193d0 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
193e0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
193f0 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
19400 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
19410 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
19420 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
19430 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74  ta-data associat
19440 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
19450 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
19460 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
19470 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
19480 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
19490 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
194a0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
194b0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
194c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
194d0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
194e0 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
194f0 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
19500 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
19510 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
19520 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
19530 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
19540 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
19550 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
19560 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
19570 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
19580 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f  eta-data.** asso
19590 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
195a0 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  Nth argument val
195b0 75 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ue to the curren
195c0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a  t SQL function.*
195d0 2a 20 63 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20  * call, where N 
195e0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
195f0 72 61 6d 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d  rameter. If no m
19600 65 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65  eta-data has bee
19610 6e 20 73 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61  n set for.** tha
19620 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 20  t value, then a 
19630 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
19640 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
19650 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
19660 61 75 78 64 61 74 61 28 29 20 69 73 20 75 73 65  auxdata() is use
19670 64 20 74 6f 20 61 73 73 6f 63 69 61 74 65 20 6d  d to associate m
19680 65 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 6e  eta-data with an
19690 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
196a0 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 74   argument. The t
196b0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
196c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
196d0 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20  he meta-data.** 
196e0 74 6f 20 62 65 20 61 73 73 6f 63 69 61 74 65 64  to be associated
196f0 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 75 73   with the Nth us
19700 65 72 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  er function argu
19710 6d 65 6e 74 20 76 61 6c 75 65 2e 20 54 68 65 20  ment value. The 
19720 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65  fourth.** parame
19730 74 65 72 20 73 70 65 63 69 66 69 65 73 20 61 20  ter specifies a 
19740 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
19750 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6f  will be called o
19760 6e 20 74 68 65 20 6d 65 74 61 2d 0a 2a 2a 20 64  n the meta-.** d
19770 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 72  ata pointer to r
19780 65 6c 65 61 73 65 20 69 74 20 77 68 65 6e 20 69  elease it when i
19790 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
197a0 65 71 75 69 72 65 64 2e 20 49 66 20 74 68 65 20  equired. If the 
197b0 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 69  .** destructor i
197c0 73 20 4e 55 4c 4c 2c 20 69 74 20 69 73 20 6e 6f  s NULL, it is no
197d0 74 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  t invoked..**.**
197e0 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
197f0 74 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65  ta-data is prese
19800 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
19810 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
19820 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
19830 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
19840 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
19850 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
19860 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
19870 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62  s and SQL variab
19880 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  les..**.** These
19890 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
198a0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
198b0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
198c0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
198d0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
198e0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
198f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
19900 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
19910 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
19920 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
19930 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
19940 74 65 78 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  text*, int, void
19950 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
19960 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
19970 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
19980 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
19990 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
199a0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
199b0 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
199c0 6c 75 65 20 66 6f 72 20 74 68 65 20 64 65 73 74  lue for the dest
199d0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
199e0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
199f0 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
19a00 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
19a10 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
19a20 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20  lt_blob()].  If 
19a30 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
19a40 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
19a50 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
19a60 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
19a70 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
19a80 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
19a90 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
19aa0 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
19ab0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
19ac0 74 72 6f 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a  troyed.  The .**
19ad0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
19ae0 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
19af0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
19b00 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
19b10 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
19b20 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
19b30 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
19b40 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
19b50 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
19b60 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
19b70 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
19b80 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
19b90 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
19ba0 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
19bb0 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
19bc0 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
19bd0 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31    See ticket #21
19be0 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  91..*/.typedef v
19bf0 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
19c00 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
19c10 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
19c20 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
19c30 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
19c40 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
19c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
19c60 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
19c70 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
19c80 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
19c90 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
19ca0 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
19cb0 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
19cc0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
19cd0 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
19ce0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
19cf0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
19d00 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
19d10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
19d20 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
19d30 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
19d40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
19d50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
19d60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
19d70 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
19d80 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
19d90 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
19da0 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
19db0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
19dc0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69   .** [sqlite3_bi
19dd0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
19de0 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79  3_bind_*] family
19df0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73   of functions us
19e00 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61  ed.** to bind va
19e10 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
19e20 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
19e30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
19e40 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a  ** Refer to the.
19e50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
19e60 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
19e70 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61  bind_* documenta
19e80 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64  tion] for.** add
19e90 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
19ea0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
19eb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
19ec0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
19ed0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
19ee0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
19ef0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
19f00 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
19f10 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
19f20 78 63 65 70 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  xception.  The.*
19f30 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  * parameter to s
19f40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
19f50 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
19f60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
19f70 29 0a 2a 2a 20 69 73 20 74 68 65 20 74 65 78 74  ).** is the text
19f80 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
19f90 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sage..**.** The 
19fa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
19fb0 6f 6f 62 69 67 28 29 20 63 61 75 73 65 20 74 68  oobig() cause th
19fc0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
19fd0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  mentation.** to 
19fe0 74 68 72 6f 77 20 61 6e 64 20 65 72 72 6f 72 20  throw and error 
19ff0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
1a000 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
1a010 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74   is to long.** t
1a020 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
1a030 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1a040 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
1a050 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
1a060 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
1a070 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
1a080 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
1a090 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
1a0a0 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
1a0b0 72 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  r..*/.void sqlit
1a0c0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
1a0d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1a0e0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1a0f0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
1a100 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1a110 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
1a120 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1a130 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
1a140 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1a150 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
1a160 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
1a170 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
1a180 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
1a190 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
1a1a0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
1a1b0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
1a1c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1a1d0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
1a1e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
1a1f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1a200 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
1a210 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
1a220 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1a230 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
1a240 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
1a250 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
1a260 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
1a270 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
1a280 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
1a290 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
1a2a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1a2b0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
1a2c0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
1a2d0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1a2e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
1a2f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1a300 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1a310 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
1a320 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1a330 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
1a340 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1a350 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
1a360 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
1a370 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
1a380 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
1a390 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
1a3a0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
1a3b0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
1a3c0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
1a3d0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
1a3e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1a3f0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
1a400 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1a410 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
1a420 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1a430 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
1a440 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
1a450 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
1a460 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
1a470 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
1a480 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
1a490 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
1a4a0 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a  quences to the.*
1a4b0 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  * [sqlite3*] han
1a4c0 64 6c 65 20 73 70 65 63 69 66 69 65 64 20 61 73  dle specified as
1a4d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1a4e0 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent. .**.** The 
1a4f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
1a500 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1a510 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
1a520 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
1a530 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
1a540 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1a550 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1a560 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1a570 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
1a580 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
1a590 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1a5a0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 20  collation16().  
1a5b0 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
1a5c0 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
1a5d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1a5e0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
1a5f0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  nt..**.** The th
1a600 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  ird argument mus
1a610 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
1a620 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
1a630 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
1a640 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20  ITE_UTF16LE] or 
1a650 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
1a660 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  , indicating tha
1a670 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c  t the user-suppl
1a680 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65  ied.** routine e
1a690 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73  xpects to be pas
1a6a0 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  sed pointers to 
1a6b0 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20  strings encoded 
1a6c0 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20  using UTF-8,.** 
1a6d0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
1a6e0 64 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62  dian or UTF-16 b
1a6f0 69 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  ig-endian respec
1a700 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20  tively..**.** A 
1a710 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
1a720 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
1a730 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
1a740 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
1a750 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  .** argument. If
1a760 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69   it is NULL, thi
1a770 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  s is the same as
1a780 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
1a790 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
1a7a0 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c  nce (so that SQL
1a7b0 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20  ite cannot call 
1a7c0 69 74 20 61 6e 79 6d 6f 72 65 29 2e 20 45 61 63  it anymore). Eac
1a7d0 68 20 74 69 6d 65 20 74 68 65 20 75 73 65 72 0a  h time the user.
1a7e0 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63  ** supplied func
1a7f0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c  tion is invoked,
1a800 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20   it is passed a 
1a810 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1a820 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  * passed as.** t
1a830 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
1a840 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  nt to sqlite3_cr
1a850 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
1a860 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
1a870 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
1a880 36 28 29 20 61 73 20 69 74 73 20 66 69 72 73 74  6() as its first
1a890 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1a8a0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1a8b0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
1a8c0 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20 72   user-supplied r
1a8d0 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73  outine are two s
1a8e0 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20  trings,.** each 
1a8f0 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
1a900 20 5b 6c 65 6e 67 74 68 2c 20 64 61 74 61 5d 20   [length, data] 
1a910 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64  pair and encoded
1a920 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
1a930 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73  .** that was pas
1a940 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
1a950 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74   argument when t
1a960 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
1a970 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67  uence was.** reg
1a980 69 73 74 65 72 65 64 2e 20 54 68 65 20 75 73 65  istered. The use
1a990 72 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  r routine should
1a9a0 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65   return negative
1a9b0 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69  , zero or positi
1a9c0 76 65 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72  ve if.** the fir
1a9d0 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
1a9e0 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
1a9f0 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
1aa00 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  n the second.** 
1aa10 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54  string. i.e. (ST
1aa20 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29  RING1 - STRING2)
1aa30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1aa40 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1aa50 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
1aa60 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
1aa70 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
1aa80 2a 2a 20 65 78 63 61 70 74 20 74 68 61 74 20 69  ** excapt that i
1aa90 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61  t takes an extra
1aaa0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
1aab0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
1aac0 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  for.** the colla
1aad0 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72  tion.  The destr
1aae0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20  uctor is called 
1aaf0 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
1ab00 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79  on is.** destroy
1ab10 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64  ed and is passed
1ab20 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
1ab30 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1ab40 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a  void* pointer.**
1ab50 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1ab60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1ab70 5f 76 32 28 29 2e 20 20 43 6f 6c 6c 61 74 69 6f  _v2().  Collatio
1ab80 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  ns are destroyed
1ab90 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72   when.** they ar
1aba0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
1abb0 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
1abc0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
1abd0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a  ation functions.
1abe0 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ** or when the [
1abf0 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61  sqlite3*] databa
1ac00 73 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f  se handle is clo
1ac10 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
1ac20 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
1ac30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
1ac40 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
1ac50 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  v2() interface i
1ac60 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
1ac70 6e 64 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  nd.** subject to
1ac80 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
1ac90 65 20 72 65 6c 65 61 73 65 73 2e 20 20 54 68 65  e releases.  The
1aca0 20 6f 74 68 65 72 20 63 6f 6c 6c 61 74 69 6f 6e   other collation
1acb0 20 63 72 65 61 74 69 6f 6e 0a 2a 2a 20 66 75 6e   creation.** fun
1acc0 63 74 69 6f 6e 73 20 61 72 65 20 73 74 61 62 6c  ctions are stabl
1acd0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1ace0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1acf0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
1ad00 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1ad10 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
1ad20 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
1ad30 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
1ad40 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
1ad50 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
1ad60 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
1ad70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1ad80 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
1ad90 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
1ada0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
1adb0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
1adc0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
1add0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
1ade0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
1adf0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
1ae00 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
1ae10 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
1ae20 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
1ae30 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
1ae40 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
1ae50 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
1ae60 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
1ae70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
1ae80 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
1ae90 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
1aea0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
1aeb0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
1aec0 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
1aed0 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
1aee0 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  ks.**.** To avoi
1aef0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
1af00 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
1af10 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
1af20 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
1af30 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
1af40 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
1af50 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
1af60 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
1af70 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1af80 20 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61   handle to be ca
1af90 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  lled whenever an
1afa0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
1afb0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
1afc0 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  .** required..**
1afd0 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74  .** If the funct
1afe0 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
1aff0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
1b000 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
1b010 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
1b020 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
1b030 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
1b040 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
1b050 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
1b060 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
1b070 64 20 69 6e 20 55 54 46 2d 38 2e 20 49 66 20 73  d in UTF-8. If s
1b080 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
1b090 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
1b0a0 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a  sed, the names.*
1b0b0 2a 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  * are passed as 
1b0c0 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
1b0d0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1b0e0 64 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65  der. A call to e
1b0f0 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ither.** functio
1b100 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65  n replaces any e
1b110 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b  xisting callback
1b120 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1b130 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1b140 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
1b150 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
1b160 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
1b170 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
1b180 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
1b190 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
1b1a0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
1b1b0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
1b1c0 31 36 28 29 2e 20 54 68 65 20 73 65 63 6f 6e 64  16(). The second
1b1d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1b1e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e   database.** han
1b1f0 64 6c 65 2e 20 54 68 65 20 74 68 69 72 64 20 61  dle. The third a
1b200 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
1b210 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
1b220 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
1b230 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ], or.** [SQLITE
1b240 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
1b250 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
1b260 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
1b270 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
1b280 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
1b290 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 54 68  ion required. Th
1b2a0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1b2b0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
1b2c0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
1b2d0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
1b2e0 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ence..**.** The 
1b2f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1b300 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
1b310 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
1b320 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
1b330 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1b340 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
1b350 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1b360 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
1b370 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
1b380 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
1b390 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2()]..*/.int sql
1b3a0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
1b3b0 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33  eeded(.  sqlite3
1b3c0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20  *, .  void*, .  
1b3d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
1b3e0 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
1b3f0 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  Rep,const char*)
1b400 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1b410 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
1b420 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
1b430 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
1b440 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
1b450 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
1b460 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
1b470 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
1b480 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
1b490 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
1b4a0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
1b4b0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
1b4c0 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
1b4d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
1b4e0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
1b4f0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
1b500 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
1b510 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
1b520 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
1b530 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
1b540 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
1b550 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1b560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
1b570 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
1b580 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
1b590 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
1b5a0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
1b5b0 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
1b5c0 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
1b5d0 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
1b5e0 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
1b5f0 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
1b600 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
1b610 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
1b620 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
1b630 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
1b640 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
1b650 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
1b660 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
1b670 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
1b680 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
1b690 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
1b6a0 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
1b6b0 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
1b6c0 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
1b6d0 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
1b6e0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1b6f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1b700 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
1b710 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
1b720 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
1b730 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
1b740 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
1b750 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b760 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
1b770 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
1b780 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ime.**.** This f
1b790 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
1b7a0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
1b7b0 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
1b7c0 63 75 74 69 6f 6e 0a 2a 2a 20 61 20 6e 75 6d 62  cution.** a numb
1b7d0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
1b7e0 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
1b7f0 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
1b800 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
1b810 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
1b820 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
1b830 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
1b840 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  h .** millisecon
1b850 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
1b860 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
1b870 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
1b880 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e   up to .** the n
1b890 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
1b8a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
1b8b0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1b8c0 65 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20  ep actually .** 
1b8d0 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
1b8e0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1b8f0 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
1b900 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
1b910 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
1b920 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
1b930 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
1b940 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
1b950 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1b960 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
1b970 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
1b980 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
1b990 20 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65   CAPI3REF:  Name
1b9a0 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
1b9b0 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
1b9c0 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 49 66 20   Files.**.** If 
1b9d0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
1b9e0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
1b9f0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
1ba00 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
1ba10 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
1ba20 65 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74  er (a.ka. direct
1ba30 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
1ba40 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
1ba50 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
1ba60 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  ite will be plac
1ba70 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
1ba80 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76  tory.  If this v
1ba90 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55  ariable.** is NU
1baa0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
1bab0 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73   SQLite does a s
1bac0 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
1bad0 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61  ropriate tempora
1bae0 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63  ry.** file direc
1baf0 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65  tory..**.** Once
1bb00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1bb10 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
1bb20 64 2c 20 63 68 61 6e 67 69 6e 67 20 74 68 69 73  d, changing this
1bb30 20 76 61 72 69 61 62 6c 65 20 77 69 6c 6c 0a 2a   variable will.*
1bb40 2a 20 69 6e 76 61 6c 69 64 61 74 65 20 74 68 65  * invalidate the
1bb50 20 63 75 72 72 65 6e 74 20 74 65 6d 70 6f 72 61   current tempora
1bb60 72 79 20 64 61 74 61 62 61 73 65 2c 20 69 66 20  ry database, if 
1bb70 61 6e 79 2e 20 20 47 65 6e 65 72 61 6c 6c 79 20  any.  Generally 
1bb80 73 70 65 61 6b 69 6e 67 2c 0a 2a 2a 20 69 74 20  speaking,.** it 
1bb90 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 69  is not safe to i
1bba0 6e 76 6f 6b 65 20 74 68 69 73 20 72 6f 75 74 69  nvoke this routi
1bbb0 6e 65 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ne after [sqlite
1bbc0 33 5f 6f 70 65 6e 28 29 5d 20 68 61 73 0a 2a 2a  3_open()] has.**
1bbd0 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f   been called..*/
1bbe0 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
1bbf0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
1bc00 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
1bc10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 54  .** CAPI3REF:  T
1bc20 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1bc30 65 20 44 61 74 61 62 73 65 20 49 73 20 49 6e 20  e Databse Is In 
1bc40 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
1bc50 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20 73  .**.** Test to s
1bc60 65 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ee whether or no
1bc70 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  t the database c
1bc80 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20  onnection is in 
1bc90 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f  autocommit.** mo
1bca0 64 65 2e 20 20 52 65 74 75 72 6e 20 54 52 55 45  de.  Return TRUE
1bcb0 20 69 66 20 69 74 20 69 73 20 61 6e 64 20 46 41   if it is and FA
1bcc0 4c 53 45 20 69 66 20 6e 6f 74 2e 20 20 41 75 74  LSE if not.  Aut
1bcd0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
1bce0 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  on.** by default
1bcf0 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69 73  .  Autocommit is
1bd00 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 42   disabled by a B
1bd10 45 47 49 4e 20 73 74 61 74 65 6d 65 6e 74 20 61  EGIN statement a
1bd20 6e 64 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a 20  nd reenabled.** 
1bd30 62 79 20 74 68 65 20 6e 65 78 74 20 43 4f 4d 4d  by the next COMM
1bd40 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 0a  IT or ROLLBACK..
1bd50 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
1bd60 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
1bd70 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
1bd80 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
1bd90 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
1bda0 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
1bdb0 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
1bdc0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
1bdd0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
1bde0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
1bdf0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
1be00 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
1be10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1be20 45 46 3a 20 20 46 69 6e 64 20 54 68 65 20 44 61  EF:  Find The Da
1be30 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 41 73  tabase Handle As
1be40 73 6f 63 69 61 74 65 64 20 57 69 74 68 20 41 20  sociated With A 
1be50 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
1be60 6e 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  nt.**.** Return 
1be70 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64  the [sqlite3*] d
1be80 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
1be90 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b 73 71  o which a.** [sq
1bea0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
1beb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1bec0 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 69   belongs..** Thi
1bed0 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61  s is the same da
1bee0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68  tabase handle th
1bef0 61 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69  at was.** the fi
1bf00 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1bf10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1bf20 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
1bf30 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68  s variants.** th
1bf40 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 20 63  at was used to c
1bf50 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
1bf60 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
1bf70 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74   place..*/.sqlit
1bf80 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
1bf90 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
1bfa0 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  mt*);.../*.** CA
1bfb0 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
1bfc0 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
1bfd0 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
1bfe0 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ks.**.** These r
1bff0 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 67 69 73  outines.** regis
1c000 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
1c010 63 74 69 6f 6e 73 20 74 6f 20 62 65 20 69 6e 76  ctions to be inv
1c020 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
1c030 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 69  transaction.** i
1c040 73 20 63 6f 6d 6d 69 74 74 65 64 20 6f 72 20 72  s committed or r
1c050 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20 54 68 65  olled back.  The
1c060 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
1c070 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
1c080 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1c090 61 63 6b 2e 20 20 49 66 20 74 68 65 20 63 61 6c  ack.  If the cal
1c0a0 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
1c0b0 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
1c0c0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
1c0d0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 63  zero, then the c
1c0e0 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
1c0f0 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
1c100 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  ck..**.** If ano
1c110 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
1c120 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
1c130 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72  istered, its pAr
1c140 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  g value is retur
1c150 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  ned..** Otherwis
1c160 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
1c170 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  ed..**.** Regist
1c180 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
1c190 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
1c1a0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
1c1b0 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f  ** For the purpo
1c1c0 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
1c1d0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
1c1e0 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
1c1f0 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  een .** rolled b
1c200 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
1c210 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
1c220 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
1c230 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
1c240 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
1c250 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
1c260 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
1c270 20 6f 63 63 75 72 2e 20 54 68 65 20 0a 2a 2a 20   occur. The .** 
1c280 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
1c290 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
1c2a0 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
1c2b0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
1c2c0 0a 2a 2a 20 62 61 63 6b 20 62 65 63 61 75 73 65  .** back because
1c2d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1c2e0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1c2f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
1c300 61 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  are experimental
1c310 20 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64 20   interfaces and 
1c320 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63  are subject to c
1c330 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  hange..*/.void *
1c340 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
1c350 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ook(sqlite3*, in
1c360 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
1c370 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
1c380 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
1c390 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
1c3a0 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64  *)(void *), void
1c3b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1c3c0 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65  REF: Data Change
1c3d0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
1c3e0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 52 65  llbacks.**.** Re
1c3f0 67 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61 63  gister a callbac
1c400 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  k function with 
1c410 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1c420 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69  nection identifi
1c430 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
1c440 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1c450 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
1c460 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
1c470 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
1c480 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e  r deleted..** An
1c490 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
1c4a0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
1c4b0 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
1c4c0 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  on for the same 
1c4d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1c4e0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
1c4f0 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  idden..**.** The
1c500 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1c510 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1c520 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
1c530 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a   invoke when a .
1c540 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
1c550 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
1c560 65 6c 65 74 65 64 2e 20 54 68 65 20 66 69 72 73  eleted. The firs
1c570 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1c580 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a  e callback is.**
1c590 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
1c5a0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
1c5b0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
1c5c0 68 6f 6f 6b 28 29 2e 20 54 68 65 20 73 65 63 6f  hook(). The seco
1c5d0 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20  nd callback .** 
1c5e0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
1c5f0 6f 66 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  of SQLITE_INSERT
1c600 2c 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  , SQLITE_DELETE 
1c610 6f 72 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  or SQLITE_UPDATE
1c620 2c 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  , depending.** o
1c630 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
1c640 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
1c650 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69  callback to be i
1c660 6e 76 6f 6b 65 64 2e 20 54 68 65 20 74 68 69 72  nvoked. The thir
1c670 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68  d and .** fourth
1c680 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
1c690 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
1c6a0 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
1c6b0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1c6c0 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  .** table name c
1c6d0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
1c6e0 66 65 63 74 65 64 20 72 6f 77 2e 20 54 68 65 20  fected row. The 
1c6f0 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
1c700 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20  arameter is .** 
1c710 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  the rowid of the
1c720 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 61 73   row. In the cas
1c730 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20  e of an update, 
1c740 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77 69  this is the rowi
1c750 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 65 20  d after .** the 
1c760 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
1c770 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70  ce..**.** The up
1c780 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74  date hook is not
1c790 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
1c7a0 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61  ternal system ta
1c7b0 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69  bles are.** modi
1c7c0 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74  fied (i.e. sqlit
1c7d0 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
1c7e0 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a  ite_sequence)..*
1c7f0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
1c800 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
1c810 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
1c820 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c  ed, its pArg val
1c830 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ue is returned..
1c840 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  ** Otherwise NUL
1c850 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
1c860 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1c870 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
1c880 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
1c890 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
1c8a0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
1c8b0 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
1c8c0 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
1c8d0 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
1c8e0 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72  3REF:  Enable Or
1c8f0 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
1c900 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 0a 2a  Pager Cache.**.*
1c910 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  * This routine e
1c920 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
1c930 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
1c940 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
1c950 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
1c960 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
1c970 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65  es between conne
1c980 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73 61  ctions to the sa
1c990 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20  me database..** 
1c9a0 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  Sharing is enabl
1c9b0 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
1c9c0 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64 20 64  nt is true and d
1c9d0 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  isabled if the a
1c9e0 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61  rgument.** is fa
1c9f0 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e  lse..**.** Begin
1ca00 6e 69 6e 67 20 69 6e 20 53 51 4c 69 74 65 20 76  ning in SQLite v
1ca10 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 63 61  ersion 3.5.0, ca
1ca20 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65  che sharing is e
1ca30 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62  nabled and disab
1ca40 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e  led.** for an en
1ca50 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 20 49  tire process.  I
1ca60 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
1ca70 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61 72   of SQLite, shar
1ca80 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c  ing was.** enabl
1ca90 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
1caa0 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
1cab0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
1cac0 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69   The cache shari
1cad0 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74  ng mode set by t
1cae0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66  his interface ef
1caf0 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71  fects all subseq
1cb00 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
1cb10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1cb20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1cb30 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  _v2()], and [sql
1cb40 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
1cb50 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61  ** Existing data
1cb60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1cb70 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68   continue use th
1cb80 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 74  e sharing mode t
1cb90 68 61 74 20 77 61 73 0a 2a 2a 20 69 6e 20 65 66  hat was.** in ef
1cba0 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65  fect at the time
1cbb0 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65   they were opene
1cbc0 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  d..**.** Virtual
1cbd0 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62   tables cannot b
1cbe0 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 68  e used with a sh
1cbf0 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68 65  ared cache.  Whe
1cc00 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  n shared.** cach
1cc10 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68  e is enabled, th
1cc20 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
1cc30 5f 6d 6f 64 75 6c 65 28 29 20 41 50 49 20 75 73  _module() API us
1cc40 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a  ed to register.*
1cc50 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * virtual tables
1cc60 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
1cc70 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  urn an error..**
1cc80 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1cc90 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1cca0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
1ccb0 61 63 68 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62  ache was.** enab
1ccc0 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
1ccd0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
1cce0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  n [SQLITE_ERROR 
1ccf0 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a  | error code].**
1cd00 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68   is returned oth
1cd10 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68  erwise..**.** Sh
1cd20 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
1cd30 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1cd40 74 20 66 6f 72 20 62 61 63 6b 77 61 72 64 20 63  t for backward c
1cd50 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
1cd60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
1cd70 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
1cd80 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
1cd90 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74  PI3REF:  Attempt
1cda0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
1cdb0 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d  mory.**.** Attem
1cdc0 70 74 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74  pt to free N byt
1cdd0 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  es of heap memor
1cde0 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
1cdf0 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a  g non-essential.
1ce00 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
1ce10 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68  tions held by th
1ce20 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
1ce30 72 79 20 28 65 78 61 6d 70 6c 65 3a 20 6d 65 6d  ry (example: mem
1ce40 6f 72 79 20 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ory .** used to 
1ce50 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20 70  cache database p
1ce60 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20  ages to improve 
1ce70 70 65 72 66 6f 72 6d 61 6e 63 65 29 2e 0a 2a 2a  performance)..**
1ce80 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
1ce90 6e 20 69 73 20 6e 6f 74 20 61 20 70 61 72 74 20  n is not a part 
1cea0 6f 66 20 73 74 61 6e 64 61 72 64 20 62 75 69 6c  of standard buil
1ceb0 64 73 2e 20 20 49 74 20 69 73 20 6f 6e 6c 79 20  ds.  It is only 
1cec0 63 72 65 61 74 65 64 0a 2a 2a 20 69 66 20 53 51  created.** if SQ
1ced0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1cee0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
1cef0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
1cf00 41 4e 41 47 45 4d 45 4e 54 20 6d 61 63 72 6f 2e  ANAGEMENT macro.
1cf10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1cf20 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
1cf30 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1cf40 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20  3REF:  Impose A 
1cf50 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
1cf60 7a 65 0a 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20 61  ze.**.** Place a
1cf70 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e   "soft" limit on
1cf80 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
1cf90 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
1cfa0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
1cfb0 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 20  .** by SQLite.  
1cfc0 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
1cfd0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
1cfe0 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20  uested .** that 
1cff0 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
1d000 20 73 70 65 63 69 66 69 65 64 20 6c 69 6d 69 74   specified limit
1d010 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  , [sqlite3_relea
1d020 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a  se_memory()] is.
1d030 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f  ** invoked one o
1d040 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
1d050 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61  free up some spa
1d060 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c  ce before the al
1d070 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d  location.** is m
1d080 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  ade..**.** The l
1d090 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
1d0a0 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69  soft", because i
1d0b0 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  f [sqlite3_relea
1d0c0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e  se_memory()] can
1d0d0 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66 66  not.** free suff
1d0e0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f  icient memory to
1d0f0 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d   prevent the lim
1d100 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78  it from being ex
1d110 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d  ceeded,.** the m
1d120 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
1d130 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68  ed anyway and th
1d140 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  e current operat
1d150 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a  ion proceeds..**
1d160 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f  .** A negative o
1d170 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
1d180 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
1d190 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
1d1a0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
1d1b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
1d1c0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
1d1d0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
1d1e0 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
1d1f0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65  xhausted..** The
1d200 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
1d210 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
1d220 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
1d230 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
1d240 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
1d250 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
1d260 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20  ft heap limit.  
1d270 42 75 74 20 69 66 20 69 74 0a 2a 2a 20 69 73 20  But if it.** is 
1d280 75 6e 61 62 6c 65 20 74 6f 20 72 65 64 75 63 65  unable to reduce
1d290 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62 65   memory usage be
1d2a0 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 6c 69 6d  low the soft lim
1d2b0 69 74 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69  it, execution wi
1d2c0 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77  ll.** continue w
1d2d0 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20  ithout error or 
1d2e0 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54  notification.  T
1d2f0 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c  his is why the l
1d300 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c  imit is .** call
1d310 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  ed a "soft" limi
1d320 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f  t.  It is adviso
1d330 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  ry only..**.** T
1d340 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
1d350 69 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  it is implemente
1d360 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
1d370 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
1d380 6d 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  m()].** interfac
1d390 65 2e 20 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  e.  Only a singl
1d3a0 65 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20 69  e memory alarm i
1d3b0 73 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  s available in t
1d3c0 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 69 6d  he default.** im
1d3d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1d3e0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
1d3f0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
1d400 6e 20 61 6c 73 6f 20 75 73 65 73 20 74 68 65 0a  n also uses the.
1d410 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20  ** memory alarm 
1d420 69 6e 74 65 72 66 61 63 65 20 69 74 20 77 69 6c  interface it wil
1d430 6c 20 69 6e 74 65 72 66 65 72 65 20 77 69 74 68  l interfere with
1d440 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
1d450 66 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65  f the.** soft he
1d460 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 75 6e 64  ap limit and und
1d470 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 20  efined behavior 
1d480 77 69 6c 6c 20 72 65 73 75 6c 74 2e 20 20 0a 2a  will result.  .*
1d490 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1d4a0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1d4b0 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .0, this routine
1d4c0 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65   only constraine
1d4d0 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  d the memory.** 
1d4e0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73  allocated by a s
1d4f0 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74  ingle thread - t
1d500 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
1d510 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75  n which this rou
1d520 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42  tine.** runs.  B
1d530 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51  eginning with SQ
1d540 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1d550 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61  .0, the soft hea
1d560 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70  p limit is.** ap
1d570 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72  plied to all thr
1d580 65 61 64 73 2e 20 20 54 68 65 20 76 61 6c 75 65  eads.  The value
1d590 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74   specified for t
1d5a0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
1d5b0 69 74 0a 2a 2a 20 69 73 20 61 6e 20 62 6f 75 6e  it.** is an boun
1d5c0 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d  d on the total m
1d5d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d5e0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73   for all threads
1d5f0 2e 20 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e  .  In.** version
1d600 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20   3.5.0 there is 
1d610 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72  no mechanism for
1d620 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65   limiting the he
1d630 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20  ap usage for.** 
1d640 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61  individual threa
1d650 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ds..*/.void sqli
1d660 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
1d670 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mit(int);../*.**
1d680 20 43 41 50 49 33 52 45 46 3a 20 20 45 78 74 72   CAPI3REF:  Extr
1d690 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f  act Metadata Abo
1d6a0 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41  ut A Column Of A
1d6b0 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 69   Table.**.** Thi
1d6c0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74  s routine.** ret
1d6d0 75 72 6e 73 20 6d 65 74 61 2d 64 61 74 61 20 61  urns meta-data a
1d6e0 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20  bout a specific 
1d6f0 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63  column of a spec
1d700 69 66 69 63 20 64 61 74 61 62 61 73 65 0a 2a 2a  ific database.**
1d710 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c   table accessibl
1d720 65 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  e using the conn
1d730 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61  ection handle pa
1d740 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
1d750 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61  t function .** a
1d760 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
1d770 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
1d780 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
1d790 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
1d7a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1d7b0 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66  rs to .** this f
1d7c0 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63  unction. The sec
1d7d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1d7e0 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65   either the name
1d7f0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1d800 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22  .** (i.e. "main"
1d810 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61  , "temp" or an a
1d820 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1d830 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
1d840 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61   specified.** ta
1d850 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20  ble or NULL. If 
1d860 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  it is NULL, then
1d870 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61   all attached da
1d880 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72  tabases are sear
1d890 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ched.** for the 
1d8a0 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  table using the 
1d8b0 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 61  same algorithm a
1d8c0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
1d8d0 6e 67 69 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a  ngine uses to .*
1d8e0 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
1d8f0 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
1d900 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  rences..**.** Th
1d910 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
1d920 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1d930 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
1d940 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
1d950 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65   column .** name
1d960 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
1d970 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
1d980 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
1d990 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
1d9a0 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  s .** may be NUL
1d9b0 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e  L..**.** Meta in
1d9c0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 74  formation is ret
1d9d0 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67  urned by writing
1d9e0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c   to the memory l
1d9f0 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20  ocations passed 
1da00 61 73 0a 2a 2a 20 74 68 65 20 35 74 68 20 61 6e  as.** the 5th an
1da10 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72  d subsequent par
1da20 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
1da30 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66  function. Any of
1da40 20 74 68 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d   these .** argum
1da50 65 6e 74 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c  ents may be NULL
1da60 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
1da70 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
1da80 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74  g element of met
1da90 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  a .** informatio
1daa0 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a  n is ommitted..*
1dab0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61  *.** <pre>.** Pa
1dac0 72 61 6d 65 74 65 72 20 20 20 20 20 4f 75 74 70  rameter     Outp
1dad0 75 74 20 54 79 70 65 20 20 20 20 20 20 44 65 73  ut Type      Des
1dae0 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d  cription.** ----
1daf0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1db00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1db10 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20 20 20  **.**   5th     
1db20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20      const char* 
1db30 20 20 20 20 20 44 61 74 61 20 74 79 70 65 0a 2a       Data type.*
1db40 2a 20 20 20 36 74 68 20 20 20 20 20 20 20 20 20  *   6th         
1db50 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20  const char*     
1db60 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 66   Name of the def
1db70 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
1db80 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74  equence .**   7t
1db90 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20  h         int   
1dba0 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20             True 
1dbb0 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61  if the column ha
1dbc0 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  s a NOT NULL con
1dbd0 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68  straint.**   8th
1dbe0 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
1dbf0 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
1dc00 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
1dc10 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d  part of the PRIM
1dc20 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68  ARY KEY.**   9th
1dc30 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
1dc40 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
1dc50 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
1dc60 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a  AUTOINCREMENT.**
1dc70 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a   </pre>.**.**.**
1dc80 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e   The memory poin
1dc90 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68  ted to by the ch
1dca0 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73  aracter pointers
1dcb0 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68   returned for th
1dcc0 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f  e .** declaratio
1dcd0 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61  n type and colla
1dce0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
1dcf0 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69   valid only unti
1dd00 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63  l the next .** c
1dd10 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69 74  all to any sqlit
1dd20 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a  e API function..
1dd30 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65  **.** If the spe
1dd40 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20  cified table is 
1dd50 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c  actually a view,
1dd60 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 69   then an error i
1dd70 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1dd80 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69  * If the specifi
1dd90 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f  ed column is "ro
1dda0 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22  wid", "oid" or "
1ddb0 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 20  _rowid_" and an 
1ddc0 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49 4d  .** INTEGER PRIM
1ddd0 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68  ARY KEY column h
1dde0 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
1ddf0 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
1de00 6e 20 74 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a  n the output .**
1de10 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1de20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c  set for the expl
1de30 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
1de40 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65  column. If there
1de50 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63   is no.** explic
1de60 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49 50  itly declared IP
1de70 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  K column, then t
1de80 68 65 20 6f 75 74 70 75 74 20 70 61 72 61 6d 65  he output parame
1de90 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20  ters are set as 
1dea0 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a  .** follows:.**.
1deb0 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
1dec0 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45  data type: "INTE
1ded0 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c  GER".**     coll
1dee0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20  ation sequence: 
1def0 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20  "BINARY".**     
1df00 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20  not null: 0.**  
1df10 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20     primary key: 
1df20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e  1.**     auto in
1df30 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f  crement: 0.** </
1df40 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  pre>.**.** This 
1df50 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61  function may loa
1df60 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63  d one or more sc
1df70 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62  hemas from datab
1df80 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e  ase files. If an
1df90 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73  .** error occurs
1dfa0 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f   during this pro
1dfb0 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20  cess, or if the 
1dfc0 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20  requested table 
1dfd0 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e  or column.** can
1dfe0 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e  not be found, an
1dff0 20 53 51 4c 49 54 45 20 65 72 72 6f 72 20 63 6f   SQLITE error co
1e000 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  de is returned a
1e010 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
1e020 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74  age.** left in t
1e030 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  he database hand
1e040 6c 65 20 28 74 6f 20 62 65 20 72 65 74 72 69 65  le (to be retrie
1e050 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ved using sqlite
1e060 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a  3_errmsg())..**.
1e070 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f  ** This API is o
1e080 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
1e090 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
1e0a0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
1e0b0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41  he.** SQLITE_ENA
1e0c0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
1e0d0 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ATA preprocessor
1e0e0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
1e0f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e100 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
1e110 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
1e120 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1e130 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
1e140 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
1e150 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
1e160 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
1e170 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
1e180 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
1e190 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
1e1a0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
1e1b0 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
1e1c0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
1e1d0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
1e1e0 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
1e1f0 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
1e200 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
1e210 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70  eclared data typ
1e220 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
1e230 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20  t **pzCollSeq,  
1e240 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f     /* OUTPUT: Co
1e250 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1e260 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   name */.  int *
1e270 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20  pNotNull,       
1e280 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
1e290 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55  : True if NOT NU
1e2a0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78  LL constraint ex
1e2b0 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  ists */.  int *p
1e2c0 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20  PrimaryKey,     
1e2d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
1e2e0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
1e2f0 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20  part of PK */.  
1e300 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20  int *pAutoinc   
1e310 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
1e320 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
1e330 6f 6c 75 6d 73 20 69 73 20 61 75 74 6f 2d 69 6e  olums is auto-in
1e340 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f  crement */.);../
1e350 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
1e360 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
1e370 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74  .**.** Attempt t
1e380 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65  o load an SQLite
1e390 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
1e3a0 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20  ry contained in 
1e3b0 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c  the file.** zFil
1e3c0 65 2e 20 20 54 68 65 20 65 6e 74 72 79 20 70 6f  e.  The entry po
1e3d0 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 20 7a  int is zProc.  z
1e3e0 50 72 6f 63 20 6d 61 79 20 62 65 20 30 20 69 6e  Proc may be 0 in
1e3f0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 0a   which case the.
1e400 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65  ** name of the e
1e410 6e 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75  ntry point defau
1e420 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  lts to "sqlite3_
1e430 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
1e440 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 5b 53  .**.** Return [S
1e450 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
1e460 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45  cess and [SQLITE
1e470 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74  _ERROR] if somet
1e480 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
1e490 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72  .**.** If an err
1e4a0 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
1e4b0 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
1e4c0 20 74 68 65 6e 20 66 69 6c 6c 20 2a 70 7a 45 72   then fill *pzEr
1e4d0 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20 65 72  rMsg with .** er
1e4e0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
1e4f0 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  .  The calling f
1e500 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66  unction should f
1e510 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a  ree this memory.
1e520 2a 2a 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ** by calling [s
1e530 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1e540 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20  **.** Extension 
1e550 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20  loading must be 
1e560 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
1e570 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
1e580 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a  ad_extension()].
1e590 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
1e5a0 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f 72 20  ing this API or 
1e5b0 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  an error will be
1e5c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e   returned..*/.in
1e5d0 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  t sqlite3_load_e
1e5e0 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69  xtension(.  sqli
1e5f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1e600 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78    /* Load the ex
1e610 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69  tension into thi
1e620 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  s database conne
1e630 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  ction */.  const
1e640 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20   char *zFile,   
1e650 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
1e660 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63  shared library c
1e670 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73  ontaining extens
1e680 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
1e690 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f  har *zProc,    /
1e6a0 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20  * Entry point.  
1e6b0 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69  Derived from zFi
1e6c0 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61  le if 0 */.  cha
1e6d0 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20  r **pzErrMsg    
1e6e0 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20     /* Put error 
1e6f0 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20  message here if 
1e700 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  not 0 */.);../*.
1e710 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e  ** CAPI3REF:  En
1e720 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
1e730 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
1e740 67 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f  g.**.** So as no
1e750 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69  t to open securi
1e760 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65  ty holes in olde
1e770 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  r applications t
1e780 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65  hat are.** unpre
1e790 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69  pared to deal wi
1e7a0 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  th extension loa
1e7b0 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d  ding, and as a m
1e7c0 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e  eans of disablin
1e7d0 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c  g.** extension l
1e7e0 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61  oading while eva
1e7f0 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74  luating user-ent
1e800 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f  ered SQL, the fo
1e810 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69  llowing.** API i
1e820 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75  s provided to tu
1e830 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  rn the [sqlite3_
1e840 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1e850 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61  ] mechanism on a
1e860 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 49 74 20 69  nd.** off.  It i
1e870 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74  s off by default
1e880 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 31  .  See ticket #1
1e890 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20  863..**.** Call 
1e8a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1e8b0 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75  h onoff==1 to tu
1e8c0 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  rn extension loa
1e8d0 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63  ding on.** and c
1e8e0 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
1e8f0 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20 69 74 20  f==0 to turn it 
1e900 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a  back off again..
1e910 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1e920 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
1e930 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62  sion(sqlite3 *db
1e940 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
1e950 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1e960 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74 73  ake Arrangements
1e970 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c   To Automaticall
1e980 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  y Load An Extens
1e990 69 6f 6e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  ion.**.** Regist
1e9a0 65 72 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20  er an extension 
1e9b0 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74  entry point that
1e9c0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
1e9d0 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  y invoked.** whe
1e9e0 6e 65 76 65 72 20 61 20 6e 65 77 20 64 61 74 61  never a new data
1e9f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1ea00 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a  is opened using.
1ea10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
1ea20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1ea30 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  en16()], or [sql
1ea40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
1ea50 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
1ea60 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61  can be invoked a
1ea70 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75  t program startu
1ea80 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65  p in order to re
1ea90 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72  gister.** one or
1eaa0 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79   more statically
1eab0 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f   linked extensio
1eac0 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  ns that will be 
1ead0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20  available.** to 
1eae0 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65  all new database
1eaf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a   connections..**
1eb00 0a 2a 2a 20 44 75 70 6c 69 63 61 74 65 20 65 78  .** Duplicate ex
1eb10 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74  tensions are det
1eb20 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67  ected so calling
1eb30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   this routine mu
1eb40 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
1eb50 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78  with the same ex
1eb60 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c  tension is harml
1eb70 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ess..**.** This 
1eb80 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61  routine stores a
1eb90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1eba0 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20  extension in an 
1ebb0 61 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73  array.** that is
1ebc0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d   obtained from m
1ebd0 61 6c 6c 6f 63 28 29 2e 20 20 49 66 20 79 6f 75  alloc().  If you
1ebe0 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65   run a memory le
1ebf0 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e  ak.** checker on
1ec00 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e   your program an
1ec10 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c  d it reports a l
1ec20 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74  eak because of t
1ec30 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68  his.** array, th
1ec40 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  en invoke [sqlit
1ec50 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74  e3_automatic_ext
1ec60 65 6e 73 69 6f 6e 5f 72 65 73 65 74 28 29 5d 20  ension_reset()] 
1ec70 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74  prior.** to shut
1ec80 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65  down to free the
1ec90 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41   memory..**.** A
1eca0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
1ecb0 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73  ons apply across
1ecc0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a   all threads..**
1ecd0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1ece0 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ce is experiment
1ecf0 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63  al and is subjec
1ed00 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a  t to change or.*
1ed10 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74  * removal in fut
1ed20 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
1ed30 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
1ed40 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
1ed50 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74  nsion(void *xEnt
1ed60 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a  ryPoint);.../*.*
1ed70 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
1ed80 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65  t Automatic Exte
1ed90 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
1eda0 0a 2a 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20  .** Disable all 
1edb0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
1edc0 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20  tered automatic 
1edd0 65 78 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69  extensions.  Thi
1ede0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  s.** routine und
1edf0 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
1ee00 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c  f all prior [sql
1ee10 69 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65  ite3_automatic_e
1ee20 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63  xtension()].** c
1ee30 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  alls..**.** This
1ee40 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61   call disabled a
1ee50 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
1ee60 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61  ons in all threa
1ee70 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ds..**.** This i
1ee80 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
1ee90 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
1eea0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1eeb0 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20  e or.** removal 
1eec0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
1eed0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
1eee0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1eef0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
1ef00 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a  on(void);.../*.*
1ef10 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ***** EXPERIMENT
1ef20 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20  AL - subject to 
1ef30 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e  change without n
1ef40 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  otice **********
1ef50 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ****.**.** The i
1ef60 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
1ef70 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
1ef80 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
1ef90 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
1efa0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
1efb0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
1efc0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
1efd0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
1efe0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
1eff0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
1f000 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
1f010 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
1f020 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
1f030 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1f040 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
1f050 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65  chanism stablize
1f060 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
1f070 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
1f080 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
1f090 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
1f0a0 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
1f0b0 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
1f0c0 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65  ./*.** Structure
1f0d0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69  s used by the vi
1f0e0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
1f0f0 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66  rface.*/.typedef
1f100 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1f110 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61  vtab sqlite3_vta
1f120 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  b;.typedef struc
1f130 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
1f140 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64  info sqlite3_ind
1f150 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66  ex_info;.typedef
1f160 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1f170 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69  vtab_cursor sqli
1f180 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b  te3_vtab_cursor;
1f190 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1f1a0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73  sqlite3_module s
1f1b0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a  qlite3_module;..
1f1c0 2f 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69  /*.** A module i
1f1d0 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72  s a class of vir
1f1e0 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61  tual tables.  Ea
1f1f0 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66  ch module is def
1f200 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e  ined.** by an in
1f210 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f  stance of the fo
1f220 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
1f230 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75  e.  This structu
1f240 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d  re consists.** m
1f250 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
1f260 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
1f270 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
1f280 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e  e3_module {.  in
1f290 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
1f2a0 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c  t (*xCreate)(sql
1f2b0 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
1f2c0 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
1f2d0 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
1f2e0 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
1f2f0 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
1f300 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
1f310 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
1f320 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e  );.  int (*xConn
1f330 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ect)(sqlite3*, v
1f340 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
1f350 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
1f360 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
1f370 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
1f380 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
1f390 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
1f3a0 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
1f3b0 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73   (*xBestIndex)(s
1f3c0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
1f3d0 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  ab, sqlite3_inde
1f3e0 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20  x_info*);.  int 
1f3f0 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73  (*xDisconnect)(s
1f400 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
1f410 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  ab);.  int (*xDe
1f420 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
1f430 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
1f440 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
1f450 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
1f460 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
1f470 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29  rsor **ppCursor)
1f480 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
1f490 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
1f4a0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
1f4b0 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65  *xFilter)(sqlite
1f4c0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
1f4d0 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73  int idxNum, cons
1f4e0 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a  t char *idxStr,.
1f4f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f500 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65  int argc, sqlite
1f510 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b  3_value **argv);
1f520 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28  .  int (*xNext)(
1f530 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
1f540 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
1f550 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
1f560 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
1f570 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
1f580 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
1f590 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
1f5a0 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  xt*, int);.  int
1f5b0 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
1f5c0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
1f5d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
1f5e0 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28  pRowid);.  int (
1f5f0 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65  *xUpdate)(sqlite
1f600 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73  3_vtab *, int, s
1f610 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c  qlite3_value **,
1f620 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
1f630 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69  );.  int (*xBegi
1f640 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
1f650 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
1f660 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
1f670 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
1f680 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73  int (*xCommit)(s
1f690 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
1f6a0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  ab);.  int (*xRo
1f6b0 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
1f6c0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
1f6d0 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74  int (*xFindFunct
1f6e0 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ion)(sqlite3_vta
1f6f0 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41  b *pVtab, int nA
1f700 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  rg, const char *
1f710 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20  zName,.         
1f720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
1f730 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
1f740 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
1f750 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
1f760 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  **),.           
1f770 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
1f780 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e   **ppArg);..  in
1f790 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c  t (*xRename)(sql
1f7a0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
1f7b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
1f7c0 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54  ew);.};../*.** T
1f7d0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
1f7e0 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20  _info structure 
1f7f0 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63  and its substruc
1f800 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f  tures is used to
1f810 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61  .** pass informa
1f820 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65  tion into and re
1f830 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20  ceive the reply 
1f840 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e  from the xBestIn
1f850 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  dex.** method of
1f860 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75   an sqlite3_modu
1f870 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20  le.  The fields 
1f880 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a  under **Inputs**
1f890 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75   are the.** inpu
1f8a0 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78  ts to xBestIndex
1f8b0 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e   and are read-on
1f8c0 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20  ly.  xBestIndex 
1f8d0 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72  inserts its.** r
1f8e0 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20  esults into the 
1f8f0 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c  **Outputs** fiel
1f900 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43  ds..**.** The aC
1f910 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
1f920 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
1f930 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
1f940 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ts of the.** for
1f950 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20  m:.**.**        
1f960 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a   column OP expr.
1f970 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69  **.** Where OP i
1f980 73 20 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f  s =, <, <=, >, o
1f990 72 20 3e 3d 2e 20 20 54 68 65 20 70 61 72 74 69  r >=.  The parti
1f9a0 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69  cular operator i
1f9b0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1f9c0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e  Constraint[].op.
1f9d0 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74    The index of t
1f9e0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  he column is sto
1f9f0 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73  red in .** aCons
1fa00 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e  traint[].iColumn
1fa10 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  .  aConstraint[]
1fa20 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20  .usable is TRUE 
1fa30 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f  if the.** expr o
1fa40 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  n the right-hand
1fa50 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61   side can be eva
1fa60 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73  luated (and thus
1fa70 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a   the constraint.
1fa80 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e  ** is usable) an
1fa90 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61  d false if it ca
1faa0 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nnot..**.** The 
1fab0 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61  optimizer automa
1fac0 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20  tically inverts 
1fad0 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72  terms of the for
1fae0 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d  m "expr OP colum
1faf0 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20  n".** and makes 
1fb00 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61  other simplifica
1fb10 74 69 6e 6f 73 20 74 6f 20 74 68 65 20 57 48 45  tinos to the WHE
1fb20 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20  RE clause in an 
1fb30 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65  attempt to.** ge
1fb40 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20  t as many WHERE 
1fb50 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74  clause terms int
1fb60 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e  o the form shown
1fb70 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62   above as possib
1fb80 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73  le..** The aCons
1fb90 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f  traint[] array o
1fba0 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52  nly reports WHER
1fbb0 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69  E clause terms i
1fbc0 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a  n the correct.**
1fbd0 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72   form that refer
1fbe0 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c   to the particul
1fbf0 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ar virtual table
1fc00 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a   being queried..
1fc10 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f  **.** Informatio
1fc20 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
1fc30 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
1fc40 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
1fc50 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72  y[]..** Each ter
1fc60 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65  m of aOrderBy re
1fc70 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  cords a column o
1fc80 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
1fc90 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lause..**.** The
1fca0 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68   xBestIndex meth
1fcb0 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f  od must fill aCo
1fcc0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20  nstraintUsage[] 
1fcd0 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  with information
1fce0 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70  .** about what p
1fcf0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73  arameters to pas
1fd00 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49  s to xFilter.  I
1fd10 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68  f argvIndex>0 th
1fd20 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d  en.** the right-
1fd30 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65  hand side of the
1fd40 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61   corresponding a
1fd50 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20  Constraint[] is 
1fd60 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64  evaluated.** and
1fd70 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67   becomes the arg
1fd80 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20  vIndex-th entry 
1fd90 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f  in argv.  If aCo
1fda0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e  nstraintUsage[].
1fdb0 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c  omit.** is true,
1fdc0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72   then the constr
1fdd0 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20  aint is assumed 
1fde0 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64  to be fully hand
1fdf0 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69  led by the.** vi
1fe00 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
1fe10 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61  is not checked a
1fe20 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a  gain by SQLite..
1fe30 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d  **.** The idxNum
1fe40 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75   and idxPtr valu
1fe50 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20  es are recorded 
1fe60 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20  and passed into 
1fe70 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69  xFilter..** sqli
1fe80 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73  te3_free() is us
1fe90 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74  ed to free idxPt
1fea0 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49  r if needToFreeI
1feb0 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a  dxPtr is true..*
1fec0 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79  *.** The orderBy
1fed0 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74  Consumed means t
1fee0 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20  hat output from 
1fef0 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63  xFilter will occ
1ff00 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72  ur in.** the cor
1ff10 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61  rect order to sa
1ff20 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20  tisfy the ORDER 
1ff30 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61  BY clause so tha
1ff40 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a  t no separate.**
1ff50 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73   sorting step is
1ff60 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1ff70 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f   The estimatedCo
1ff80 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65  st value is an e
1ff90 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63  stimate of the c
1ffa0 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65  ost of doing the
1ffb0 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c  .** particular l
1ffc0 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73  ookup.  A full s
1ffd0 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77  can of a table w
1ffe0 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68  ith N entries sh
1fff0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63  ould have.** a c
20000 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e  ost of N.  A bin
20010 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20  ary search of a 
20020 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69  table of N entri
20030 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61  es should have a
20040 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72  .** cost of appr
20050 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29  oximately log(N)
20060 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
20070 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b  te3_index_info {
20080 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a  .  /* Inputs */.
20090 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e    const int nCon
200a0 73 74 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20  straint;     /* 
200b0 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  Number of entrie
200c0 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  s in aConstraint
200d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 74 72 75   */.  const stru
200e0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
200f0 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
20100 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
20110 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
20120 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
20130 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
20140 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
20150 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
20160 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
20170 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
20180 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
20190 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
201a0 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
201b0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
201c0 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
201d0 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
201e0 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
201f0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
20200 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
20210 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 63  ignore */.  } *c
20220 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74  onst aConstraint
20230 3b 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  ;      /* Table 
20240 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
20250 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
20260 20 63 6f 6e 73 74 20 69 6e 74 20 6e 4f 72 64 65   const int nOrde
20270 72 42 79 3b 20 20 20 20 20 20 20 20 2f 2a 20 4e  rBy;        /* N
20280 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
20290 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
202a0 6c 61 75 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  lause */.  const
202b0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
202c0 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a  index_orderby {.
202d0 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
202e0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
202f0 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20  * Column number 
20300 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
20310 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20   char desc;     
20320 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45    /* True for DE
20330 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41  SC.  False for A
20340 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73  SC. */.  } *cons
20350 74 20 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20  t aOrderBy;     
20360 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52      /* The ORDER
20370 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a 20   BY clause */.. 
20380 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20   /* Outputs */. 
20390 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
203a0 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
203b0 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74  _usage {.    int
203c0 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20   argvIndex;     
203d0 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20        /* if >0, 
203e0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61  constraint is pa
203f0 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46  rt of argv to xF
20400 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73  ilter */.    uns
20410 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b  igned char omit;
20420 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20        /* Do not 
20430 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20  code a test for 
20440 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
20450 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43  */.  } *const aC
20460 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a  onstraintUsage;.
20470 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20    int idxNum;   
20480 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
20490 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69  Number used to i
204a0 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65  dentify the inde
204b0 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78  x */.  char *idx
204c0 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20  Str;            
204d0 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73    /* String, pos
204e0 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  sibly obtained f
204f0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
20500 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64  oc */.  int need
20510 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20  ToFreeIdxStr;   
20520 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74     /* Free idxSt
20530 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  r using sqlite3_
20540 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a  free() if true *
20550 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43  /.  int orderByC
20560 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f  onsumed;       /
20570 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74  * True if output
20580 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65   is already orde
20590 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20  red */.  double 
205a0 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20  estimatedCost;  
205b0 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64      /* Estimated
205c0 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74   cost of using t
205d0 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a  his index */.};.
205e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
205f0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
20600 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  EQ    2.#define 
20610 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
20620 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a  STRAINT_GT    4.
20630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
20640 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
20650 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20  LE    8.#define 
20660 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
20670 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36  STRAINT_LT    16
20680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20690 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
206a0 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e  _GE    32.#defin
206b0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
206c0 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20  ONSTRAINT_MATCH 
206d0 36 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72  64../*.** This r
206e0 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74  outine is used t
206f0 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77  o register a new
20700 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74   module name wit
20710 68 20 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63  h an SQLite.** c
20720 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75  onnection.  Modu
20730 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65  le names must be
20740 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f   registered befo
20750 72 65 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a  re creating new.
20760 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
20770 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c  s on the module,
20780 20 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67   or before using
20790 20 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 72   preexisting vir
207a0 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f  tual.** tables o
207b0 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f  f the module..*/
207c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
207d0 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71  ate_module(.  sq
207e0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
207f0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
20800 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
20810 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
20820 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
20830 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
20840 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
20850 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
20860 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
20870 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d  odule *,    /* M
20880 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
20890 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
208a0 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *               
208b0 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
208c0 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
208d0 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a  /xConnect */.);.
208e0 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  ./*.** This rout
208f0 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ine is identical
20900 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
20910 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20  create_module() 
20920 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a  method above,.**
20930 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
20940 61 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63  allows a destruc
20950 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  tor function to 
20960 62 65 20 73 70 65 63 69 66 69 65 64 2e 20 49 74  be specified. It
20970 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65   is.** even more
20980 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68   experimental th
20990 61 6e 20 74 68 65 20 72 65 73 74 20 6f 66 20 74  an the rest of t
209a0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
209b0 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71  s API..*/.int sq
209c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
209d0 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ule_v2(.  sqlite
209e0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
209f0 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
20a00 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
20a10 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
20a20 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
20a30 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
20a40 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
20a50 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
20a60 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
20a70 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f  e *,    /* Metho
20a80 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
20a90 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  e */.  void *,  
20aa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20ab0 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
20ac0 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
20ad0 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28  nnect */.  void(
20ae0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
20af0 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20  )     /* Module 
20b00 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
20b10 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ion */.);../*.**
20b20 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d   Every module im
20b30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
20b40 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  s a subclass of 
20b50 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
20b60 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65  ructure.** to de
20b70 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75  scribe a particu
20b80 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  lar instance of 
20b90 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63  the module.  Eac
20ba0 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a  h subclass will.
20bb0 2a 2a 20 62 65 20 74 61 79 6c 6f 72 65 64 20 74  ** be taylored t
20bc0 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
20bd0 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  eeds of the modu
20be0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
20bf0 6e 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70  n.   The.** purp
20c00 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65  ose of this supe
20c10 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66  rclass is to def
20c20 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c  ine certain fiel
20c30 64 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d  ds that are comm
20c40 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64  on.** to all mod
20c50 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
20c60 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75  ons..**.** Virtu
20c70 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64  al tables method
20c80 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72  s can set an err
20c90 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73  or message by as
20ca0 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72  signing a.** str
20cb0 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
20cc0 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
20cd0 66 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  f() to zErrMsg. 
20ce0 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
20cf0 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
20d00 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
20d10 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
20d20 79 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  y a call to sqli
20d30 74 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72  te3_free().** pr
20d40 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67  ior to assigning
20d50 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f   a new string to
20d60 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72   zErrMsg.  After
20d70 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
20d80 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72  ge.** is deliver
20d90 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69  ed up to the cli
20da0 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ent application,
20db0 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
20dc0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
20dd0 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71  y.** freed by sq
20de0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64  lite3_free() and
20df0 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
20e00 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65  ld will be zeroe
20e10 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74  d.  Note.** that
20e20 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
20e30 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66  () and sqlite3_f
20e40 72 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f  ree() are used o
20e50 6e 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69  n the zErrMsg fi
20e60 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72  eld.** since vir
20e70 74 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20  tual tables are 
20e80 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65  commonly impleme
20e90 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65  nted in loadable
20ea0 20 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63   extensions whic
20eb0 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65  h.** do not have
20ec0 20 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74   access to sqlit
20ed0 65 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73  e3MPrintf() or s
20ee0 71 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f  qlite3Free()..*/
20ef0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
20f00 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73  vtab {.  const s
20f10 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
20f20 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20  Module;  /* The 
20f30 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20  module for this 
20f40 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f  virtual table */
20f50 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20  .  int nRef;    
20f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20f70 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72     /* Used inter
20f80 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20  nally */.  char 
20f90 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20  *zErrMsg;       
20fa0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
20fb0 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d  ror message from
20fc0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
20fd0 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  () */.  /* Virtu
20fe0 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
20ff0 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
21000 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
21010 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
21020 0a 7d 3b 0a 0a 2f 2a 20 45 76 65 72 79 20 6d 6f  .};../* Every mo
21030 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
21040 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
21050 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  ass of the follo
21060 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a  wing structure.*
21070 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  * to describe cu
21080 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
21090 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61   into the virtua
210a0 6c 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20  l table and are 
210b0 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
210c0 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
210d0 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
210e0 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
210f0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70  using the.** xOp
21100 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
21110 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d   module.  Each m
21120 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
21130 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65  tion will define
21140 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
21150 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75  of a cursor stru
21160 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74  cture to suit it
21170 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  s own needs..**.
21180 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61  ** This supercla
21190 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64  ss exists in ord
211a0 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65  er to define fie
211b0 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f  lds of the curso
211c0 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f  r that.** are co
211d0 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c  mmon to all impl
211e0 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a  ementations..*/.
211f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
21200 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
21210 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
21220 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74  ab;      /* Virt
21230 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69  ual table of thi
21240 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a  s cursor */.  /*
21250 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
21260 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
21270 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
21280 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
21290 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
212a0 20 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64   The xCreate and
212b0 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64   xConnect method
212c0 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73  s of a module us
212d0 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  e the following 
212e0 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72  API.** to declar
212f0 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68  e the format (th
21300 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61  e names and data
21310 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  types of the col
21320 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20  umns) of.** the 
21330 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74  virtual tables t
21340 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a  hey implement..*
21350 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65  /.int sqlite3_de
21360 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74  clare_vtab(sqlit
21370 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
21380 2a 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a  *zCreateTable);.
21390 0a 2f 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  ./*.** Virtual t
213a0 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64  ables can provid
213b0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  e alternative im
213c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
213d0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73   functions.** us
213e0 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e  ing the xFindFun
213f0 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42  ction method.  B
21400 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f  ut global versio
21410 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63  ns of those func
21420 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78  tions.** must ex
21430 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ist in order to 
21440 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  be overloaded..*
21450 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61  *.** This API ma
21460 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
21470 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
21480 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
21490 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
214a0 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
214b0 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
214c0 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
214d0 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
214e0 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
214f0 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
21500 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
21510 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70  reated.  The imp
21520 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
21530 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
21540 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
21550 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
21560 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
21570 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
21580 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
21590 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
215a0 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
215b0 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
215c0 74 6f 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f  to be a place-ho
215d0 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68  lder function th
215e0 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f  at can be overlo
215f0 61 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75  aded.** by virtu
21600 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  al tables..**.**
21610 20 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64   This API should
21620 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70   be considered p
21630 61 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75  art of the virtu
21640 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
21650 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20  ce,.** which is 
21660 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
21670 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
21680 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
21690 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63  e3_overload_func
216a0 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63  tion(sqlite3*, c
216b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
216c0 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b  Name, int nArg);
216d0 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ../*.** The inte
216e0 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
216f0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
21700 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f  nism defined abo
21710 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74  ve (back up.** t
21720 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61  o a comment rema
21730 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74  rkably similar t
21740 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63  o this one) is c
21750 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
21760 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
21770 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
21780 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
21790 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
217a0 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
217b0 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
217c0 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
217d0 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
217e0 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
217f0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
21800 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
21810 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
21820 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
21830 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
21840 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
21850 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
21860 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
21870 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
21880 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52  .**.****** EXPER
21890 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63  IMENTAL - subjec
218a0 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
218b0 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a  out notice *****
218c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a  *********.*/../*
218d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20  .** CAPI3REF: A 
218e0 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65  Handle To An Ope
218f0 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 41 6e 20  n BLOB.**.** An 
21900 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
21910 66 6f 6c 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65  following opaque
21920 20 73 74 72 75 63 74 75 72 65 20 69 73 20 75 73   structure is us
21930 65 64 20 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73  ed to .** repres
21940 65 6e 74 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64  ent an blob-hand
21950 6c 65 2e 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64  le.  A blob-hand
21960 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79  le is created by
21970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
21980 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65  b_open()] and de
21990 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
219a0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
219b0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
219c0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
219d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
219e0 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72  b_write()] inter
219f0 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20  faces.** can be 
21a00 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20  used to read or 
21a10 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73  write small subs
21a20 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ections of the b
21a30 6c 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  lob..** The [sql
21a40 74 69 65 33 5f 62 6c 6f 62 5f 73 69 7a 65 28 29  tie3_blob_size()
21a50 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
21a60 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
21a70 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62  the.** blob in b
21a80 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ytes..*/.typedef
21a90 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
21aa0 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f  blob sqlite3_blo
21ab0 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  b;../*.** CAPI3R
21ac0 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20  EF: Open A BLOB 
21ad0 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20  For Incremental 
21ae0 49 2f 4f 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 61  I/O.**.** Open a
21af0 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20 62   handle to the b
21b00 6c 6f 62 20 6c 6f 63 61 74 65 64 20 69 6e 20 72  lob located in r
21b10 6f 77 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e  ow iRow,, column
21b20 20 7a 43 6f 6c 75 6d 6e 2c 20 0a 2a 2a 20 74 61   zColumn, .** ta
21b30 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
21b40 74 61 62 61 73 65 20 7a 44 62 2e 20 69 2e 65 2e  tabase zDb. i.e.
21b50 20 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74   the same blob t
21b60 68 61 74 20 77 6f 75 6c 64 0a 2a 2a 20 62 65 20  hat would.** be 
21b70 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a  selected by:.**.
21b80 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
21b90 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46  SELECT zColumn F
21ba0 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57  ROM zDb.zTable W
21bb0 48 45 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f  HERE rowid = iRo
21bc0 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a  w;.** </pre>.**.
21bd0 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20  ** If the flags 
21be0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
21bf0 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20  -zero, the blob 
21c00 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a  is opened for .*
21c10 2a 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65  * read and write
21c20 20 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 69   access. If it i
21c30 73 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62  s zero, the blob
21c40 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
21c50 65 61 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a  ead .** access..
21c60 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
21c70 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
21c80 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68   returned and th
21c90 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74  e new .** [sqlit
21ca0 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68  e3_blob | blob h
21cb0 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65  andle] is writte
21cc0 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 0a 2a 2a  n to *ppBlob..**
21cd0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   Otherwise an er
21ce0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
21cf0 72 6e 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79  rned and .** any
21d00 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74   value written t
21d10 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64  o *ppBlob should
21d20 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
21d30 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54  the caller..** T
21d40 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74  his function set
21d50 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2d 68  s the database-h
21d60 61 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65  andle error code
21d70 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20   and message.** 
21d80 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b  accessible via [
21d90 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
21da0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
21db0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
21dc0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f  t sqlite3_blob_o
21dd0 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  pen(.  sqlite3*,
21de0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
21df0 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  Db,.  const char
21e00 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73   *zTable,.  cons
21e10 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c  t char *zColumn,
21e20 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  .  sqlite3_int64
21e30 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61   iRow,.  int fla
21e40 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c  gs,.  sqlite3_bl
21e50 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a  ob **ppBlob.);..
21e60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21e70 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61   Close A BLOB Ha
21e80 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65  ndle.**.** Close
21e90 20 61 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65   an open [sqlite
21ea0 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61  3_blob | blob ha
21eb0 6e 64 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndle]..*/.int sq
21ec0 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
21ed0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
21ee0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21ef0 46 3a 20 20 52 65 74 75 72 6e 20 54 68 65 20 53  F:  Return The S
21f00 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42  ize Of An Open B
21f10 4c 4f 42 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  LOB.**.** Return
21f20 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74   the size in byt
21f30 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 61  es of the blob a
21f40 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68  ccessible via th
21f50 65 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  e open .** [sqli
21f60 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d  te3_blob | blob-
21f70 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61  handle] passed a
21f80 73 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  s an argument..*
21f90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
21fa0 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ob_bytes(sqlite3
21fb0 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
21fc0 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 61 64   CAPI3REF:  Read
21fd0 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f   Data From A BLO
21fe0 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a  B Incrementally.
21ff0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
22000 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72  ion is used to r
22010 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e  ead data from an
22020 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   open .** [sqlit
22030 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68  e3_blob | blob-h
22040 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61  andle] into a ca
22050 6c 6c 65 72 20 73 75 70 70 6c 69 65 64 20 62 75  ller supplied bu
22060 66 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73  ffer..** n bytes
22070 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
22080 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 0a  ied into buffer.
22090 2a 2a 20 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70  ** z from the op
220a0 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e  en blob, startin
220b0 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
220c0 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75  set..**.** On su
220d0 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b  ccess, SQLITE_OK
220e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74   is returned. Ot
220f0 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20  herwise, an .** 
22100 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
22110 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64  SQLite error cod
22120 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  e] or an.** [SQL
22130 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
22140 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20   extended error 
22150 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
22160 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
22170 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69  3_blob_read(sqli
22180 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64  te3_blob *, void
22190 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20   *z, int n, int 
221a0 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a  iOffset);../*.**
221b0 20 43 41 50 49 33 52 45 46 3a 20 20 57 72 69 74   CAPI3REF:  Writ
221c0 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c  e Data Into A BL
221d0 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79  OB Incrementally
221e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
221f0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
22200 77 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20  write data into 
22210 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c  an open .** [sql
22220 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
22230 2d 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20  -handle] from a 
22240 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 62 75  user supplied bu
22250 66 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73  ffer..** n bytes
22260 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
22270 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66  ied from the buf
22280 66 65 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  fer.** pointed t
22290 6f 20 62 79 20 7a 20 69 6e 74 6f 20 74 68 65 20  o by z into the 
222a0 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74  open blob, start
222b0 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
222c0 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ffset..**.** If 
222d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
222e0 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d  b | blob-handle]
222f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
22300 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
22310 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20   was not opened 
22320 66 6f 72 20 77 72 69 74 69 6e 67 20 28 74 68 65  for writing (the
22330 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
22340 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
22350 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61  b_open()].*** wa
22360 73 20 7a 65 72 6f 29 2c 20 74 68 69 73 20 66 75  s zero), this fu
22370 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
22380 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d  SQLITE_READONLY]
22390 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
223a0 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d  ction may only m
223b0 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e  odify the conten
223c0 74 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20  ts of the blob, 
223d0 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73  it is.** not pos
223e0 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73  sible to increas
223f0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  e the size of a 
22400 62 6c 6f 62 20 75 73 69 6e 67 20 74 68 69 73 20  blob using this 
22410 41 50 49 2e 20 49 66 0a 2a 2a 20 6f 66 66 73 65  API. If.** offse
22420 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
22430 73 20 74 68 61 6e 20 6e 20 62 79 74 65 73 20 66  s than n bytes f
22440 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
22450 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51  he blob, .** [SQ
22460 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
22470 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
22480 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a  ata is written..
22490 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
224a0 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  , SQLITE_OK is r
224b0 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69  eturned. Otherwi
224c0 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49  se, an .** [SQLI
224d0 54 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74  TE_ERROR | SQLit
224e0 65 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72  e error code] or
224f0 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   an.** [SQLITE_I
22500 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
22510 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
22520 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   is returned..*/
22530 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
22540 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f  b_write(sqlite3_
22550 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f  blob *, const vo
22560 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e  id *z, int n, in
22570 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
22580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 56 69  ** CAPI3REF:  Vi
22590 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65  rtual File Syste
225a0 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20  m Objects.**.** 
225b0 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79  A virtual filesy
225c0 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e  stem (VFS) is an
225d0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
225e0 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51  bject.** that SQ
225f0 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74  Lite uses to int
22600 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68  eract.** with th
22610 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
22620 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
22630 4d 6f 73 74 20 62 75 69 6c 64 73 20 63 6f 6d 65  Most builds come
22640 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c   with a.** singl
22650 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68  e default VFS th
22660 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  at is appropriat
22670 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63  e for the host c
22680 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20  omputer..** New 
22690 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67  VFSes can be reg
226a0 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73  istered and exis
226b0 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62  ting VFSes can b
226c0 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a  e unregistered..
226d0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
226e0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
226f0 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  provided..**.** 
22700 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
22710 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
22720 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
22730 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
22740 6e 20 69 74 73 0a 2a 2a 20 6e 61 6d 65 2e 20 20  n its.** name.  
22750 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
22760 65 6e 73 69 74 69 76 65 2e 20 20 49 66 20 74 68  ensitive.  If th
22770 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c  ere is no match,
22780 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
22790 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
227a0 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20   If zVfsName is 
227b0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65  NULL then the de
227c0 66 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73  fault .** VFS is
227d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
227e0 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72   New VFSes are r
227f0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73  egistered with s
22800 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
22810 74 65 72 28 29 2e 20 20 45 61 63 68 0a 2a 2a 20  ter().  Each.** 
22820 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20  new VFS becomes 
22830 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
22840 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20  if the makeDflt 
22850 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20  flag is set..** 
22860 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e  The same VFS can
22870 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
22880 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  ultiple times wi
22890 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a  thout injury..**
228a0 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73   To make an exis
228b0 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68  ting VFS into th
228c0 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72  e default VFS, r
228d0 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e  egister it again
228e0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b  .** with the mak
228f0 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 0a  eDflt flag set..
22900 2a 2a 20 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65  ** .** Unregiste
22910 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65  r a VFS with the
22920 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72   sqlite3_vfs_unr
22930 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66  egister() interf
22940 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64  ace..** If the d
22950 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e  efault VFS is un
22960 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74  registered, anot
22970 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65  her VFS is chose
22980 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61  n as.** the defa
22990 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65  ult.  The choice
229a0 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53   for the new VFS
229b0 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a   is arbitrary..*
229c0 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73  /.sqlite3_vfs *s
229d0 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
229e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
229f0 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  Name);.int sqlit
22a00 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
22a10 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
22a20 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74  t makeDflt);.int
22a30 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72   sqlite3_vfs_unr
22a40 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f  egister(sqlite3_
22a50 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  vfs*);../*.** CA
22a60 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 0a  PI3REF: Mutexes.
22a70 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
22a80 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
22a90 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68   routines for th
22aa0 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e  read.** synchron
22ab0 69 7a 61 74 69 6f 6e 2e 20 20 54 68 6f 75 67 68  ization.  Though
22ac0 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64   they are intend
22ad0 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a  ed for internal.
22ae0 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65  ** use by SQLite
22af0 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b  , code that link
22b00 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65  s against SQLite
22b10 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64   is.** permitted
22b20 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74   to use any of t
22b30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
22b40 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
22b50 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74  source code cont
22b60 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ains multiple im
22b70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 0a 2a  plementations .*
22b80 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78  * of these mutex
22b90 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61   routines.  An a
22ba0 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65  ppropriate imple
22bb0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
22bc0 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74  selected automat
22bd0 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c  ically at compil
22be0 65 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c  e-time.  The fol
22bf0 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d  lowing.** implem
22c00 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76  entations are av
22c10 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53  ailable in the S
22c20 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a  QLite core:.**.*
22c30 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
22c40 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
22c50 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20  HREAD.** <li>   
22c60 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 49 4e  SQLITE_MUTEX_WIN
22c70 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
22c80 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20  E_MUTEX_NOOP.** 
22c90 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
22ca0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f  SQLITE_MUTEX_NOO
22cb0 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  P implementation
22cc0 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75   is a set of rou
22cd0 74 69 6e 65 73 20 0a 2a 2a 20 74 68 61 74 20 64  tines .** that d
22ce0 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b  oes no real lock
22cf0 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f  ing and is appro
22d00 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69  priate for use i
22d10 6e 20 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74  n .** a single-t
22d20 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
22d30 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ion.  The SQLITE
22d40 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a  _MUTEX_PTHREAD.*
22d50 2a 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  * and SQLITE_MUT
22d60 45 58 5f 57 49 4e 20 69 6d 70 6c 65 6d 65 6e 74  EX_WIN implement
22d70 61 74 69 6f 6e 73 20 61 72 65 20 61 70 70 72 6f  ations are appro
22d80 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 75 73  priate for.** us
22d90 65 20 6f 6e 20 75 6e 69 78 20 61 6e 64 20 77 69  e on unix and wi
22da0 6e 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  ndows..** .** If
22db0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
22dc0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
22dd0 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46  ITE_MUTEX_APPDEF
22de0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a   preprocessor.**
22df0 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28   macro defined (
22e00 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d  with "-DSQLITE_M
22e10 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c  UTEX_APPDEF=1"),
22e20 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a   then no mutex.*
22e30 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
22e40 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74   is included wit
22e50 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 20  h the library.  
22e60 54 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e 74  The.** mutex int
22e70 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
22e80 64 65 66 69 6e 65 64 20 68 65 72 65 20 62 65 63  defined here bec
22e90 6f 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a 20  ome external.** 
22ea0 72 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74 68  references in th
22eb0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
22ec0 20 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c 65   for which imple
22ed0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d 75  mentations.** mu
22ee0 73 74 20 62 65 20 70 72 6f 76 69 64 65 64 20 62  st be provided b
22ef0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
22f00 6e 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69 74  n.  This facilit
22f10 79 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20 61  y allows an.** a
22f20 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
22f30 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51  links against SQ
22f40 4c 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65 20  Lite to provide 
22f50 69 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a 2a  its own mutex.**
22f60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
22f70 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
22f80 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  o modify the SQL
22f90 69 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20  ite core..**.** 
22fa0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
22fb0 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  x_alloc() routin
22fc0 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65  e allocates a ne
22fd0 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72  w.** mutex and r
22fe0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
22ff0 20 74 6f 20 69 74 2e 20 20 49 66 20 69 74 20 72   to it.  If it r
23000 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74  eturns NULL.** t
23010 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61  hat means that a
23020 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74   mutex could not
23030 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20   be allocated.  
23040 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75  SQLite.** will u
23050 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20  nwind its stack 
23060 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72  and return an er
23070 72 6f 72 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ror.  The argume
23080 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
23090 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69  _mutex_alloc() i
230a0 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
230b0 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
230c0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
230d0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
230e0 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20  EX_FAST.** <li> 
230f0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
23100 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CURSIVE.** <li> 
23110 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
23120 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c  ATIC_MASTER.** <
23130 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
23140 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20  X_STATIC_MEM.** 
23150 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
23160 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a  EX_STATIC_MEM2.*
23170 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
23180 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
23190 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
231a0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
231b0 55 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  U.** </ul>.**.**
231c0 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63   The first two c
231d0 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73  onstants cause s
231e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
231f0 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a  oc() to create.*
23200 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20  * a new mutex.  
23210 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73  The new mutex is
23220 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20   recursive when 
23230 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
23240 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65  URSIVE.** is use
23250 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73  d but not necess
23260 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51  arily so when SQ
23270 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
23280 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20  is used..** The 
23290 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
232a0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
232b0 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73  ed to make a dis
232c0 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
232d0 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  een SQLITE_MUTEX
232e0 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53  _RECURSIVE and S
232f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
23300 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   if it does.** n
23310 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 42 75 74  ot want to.  But
23320 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
23330 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75  y request a recu
23340 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a  rsive mutex in.*
23350 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74  * cases where it
23360 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e   really needs on
23370 65 2e 20 20 49 66 20 61 20 66 61 73 74 65 72 20  e.  If a faster 
23380 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75  non-recursive mu
23390 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
233a0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
233b0 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70  le on the host p
233c0 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74  latform, the mut
233d0 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20  ex subsystem.** 
233e0 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 63  might return suc
233f0 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73  h a mutex in res
23400 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f  ponse to SQLITE_
23410 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a  MUTEX_FAST..**.*
23420 2a 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f  * The other allo
23430 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74  wed parameters t
23440 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
23450 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74  alloc() each ret
23460 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  urn.** a pointer
23470 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65   to a static pre
23480 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20  existing mutex. 
23490 20 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75 74   Four static mut
234a0 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  exes are.** used
234b0 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
234c0 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
234d0 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  e.  Future versi
234e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
234f0 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f   may add additio
23500 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78  nal static mutex
23510 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65  es.  Static mute
23520 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65  xes are for inte
23530 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53  rnal.** use by S
23540 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70  QLite only.  App
23550 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
23560 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65  se SQLite mutexe
23570 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20  s should.** use 
23580 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63  only the dynamic
23590 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65   mutexes returne
235a0 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45  d by SQLITE_MUTE
235b0 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c  X_FAST or.** SQL
235c0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
235d0 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  IVE..**.** Note 
235e0 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74  that if one of t
235f0 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
23600 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c   parameters (SQL
23610 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a  ITE_MUTEX_FAST.*
23620 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45  * or SQLITE_MUTE
23630 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20  X_RECURSIVE) is 
23640 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65  used then sqlite
23650 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a  3_mutex_alloc().
23660 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66  ** returns a dif
23670 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20  ferent mutex on 
23680 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 42 75 74  every call.  But
23690 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 20   for the static 
236a0 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c  .** mutex types,
236b0 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20   the same mutex 
236c0 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65  is returned on e
236d0 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68  very call that h
236e0 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  as.** the same t
236f0 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  ype number..**.*
23700 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  * The sqlite3_mu
23710 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69  tex_free() routi
23720 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ne deallocates a
23730 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61   previously.** a
23740 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63  llocated dynamic
23750 20 6d 75 74 65 78 2e 20 20 53 51 4c 69 74 65 20   mutex.  SQLite 
23760 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65  is careful to de
23770 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a  allocate every.*
23780 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  * dynamic mutex 
23790 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65  that it allocate
237a0 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20  s.  The dynamic 
237b0 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74  mutexes must not
237c0 20 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65 20 77   be in .** use w
237d0 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61  hen they are dea
237e0 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d  llocated.  Attem
237f0 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63  pting to dealloc
23800 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20  ate a static.** 
23810 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e  mutex results in
23820 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
23830 69 6f 72 2e 20 20 53 51 4c 69 74 65 20 6e 65 76  ior.  SQLite nev
23840 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a  er deallocates.*
23850 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78  * a static mutex
23860 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23870 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
23880 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75  ) and sqlite3_mu
23890 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e  tex_try() routin
238a0 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f  es attempt.** to
238b0 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20   enter a mutex. 
238c0 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
238d0 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69  ad is already wi
238e0 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a  thin the mutex,.
238f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
23900 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c  _enter() will bl
23910 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ock and sqlite3_
23920 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c  mutex_try() will
23930 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
23940 45 5f 42 55 53 59 2e 20 20 54 68 65 20 73 71 6c  E_BUSY.  The sql
23950 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
23960 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23970 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20  ns SQLITE_OK.** 
23980 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20  upon successful 
23990 65 6e 74 72 79 2e 20 20 4d 75 74 65 78 65 73 20  entry.  Mutexes 
239a0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 53 51  created using SQ
239b0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
239c0 53 49 56 45 20 63 61 6e 0a 2a 2a 20 62 65 20 65  SIVE can.** be e
239d0 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  ntered multiple 
239e0 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d  times by the sam
239f0 65 20 74 68 72 65 61 64 2e 20 20 49 6e 20 73 75  e thread.  In su
23a00 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a  ch cases the,.**
23a10 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65   mutex must be e
23a20 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e  xited an equal n
23a30 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62  umber of times b
23a40 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68  efore another th
23a50 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65  read.** can ente
23a60 72 2e 20 20 49 66 20 74 68 65 20 73 61 6d 65 20  r.  If the same 
23a70 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20  thread tries to 
23a80 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 20  enter any other 
23a90 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 0a 2a 2a  kind of mutex.**
23aa0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
23ab0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
23ac0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 20 53 51   undefined.   SQ
23ad0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
23ae0 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20  exhibit.** such 
23af0 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20  behavior in its 
23b00 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78  own use of mutex
23b10 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  es..**.** The sq
23b20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
23b30 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74  e() routine exit
23b40 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77  s a mutex that w
23b50 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
23b60 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20   entered by the 
23b70 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 54 68  same thread.  Th
23b80 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
23b90 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68   undefined if th
23ba0 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63  e mutex is not c
23bb0 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
23bc0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69   by the.** calli
23bd0 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20  ng thread or is 
23be0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c  not currently al
23bf0 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65  located.  SQLite
23c00 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64   will.** never d
23c10 6f 20 65 69 74 68 65 72 2e 0a 2a 2a 0a 2a 2a 20  o either..**.** 
23c20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
23c30 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d  e3_mutex_held()]
23c40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75   and [sqlite3_mu
23c50 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a  tex_notheld()]..
23c60 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  */.sqlite3_mutex
23c70 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   *sqlite3_mutex_
23c80 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
23c90 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66   sqlite3_mutex_f
23ca0 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ree(sqlite3_mute
23cb0 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  x*);.void sqlite
23cc0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71  3_mutex_enter(sq
23cd0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69  lite3_mutex*);.i
23ce0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nt sqlite3_mutex
23cf0 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74  _try(sqlite3_mut
23d00 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ex*);.void sqlit
23d10 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73  e3_mutex_leave(s
23d20 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
23d30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23d40 20 4d 75 74 65 78 20 56 65 72 69 66 63 61 74 69   Mutex Verifcati
23d50 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
23d60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  * The sqlite3_mu
23d70 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73  tex_held() and s
23d80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
23d90 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a  held() routines.
23da0 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ** are intended 
23db0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
23dc0 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
23dd0 74 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ts.  The SQLite 
23de0 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73  core.** never us
23df0 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  es these routine
23e00 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 65 20  s except inside 
23e10 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64 20  an assert() and 
23e20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
23e30 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20 66  are advised to f
23e40 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f  ollow the lead o
23e50 66 20 74 68 65 20 63 6f 72 65 2e 20 20 54 68 65  f the core.  The
23e60 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72   core only.** pr
23e70 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74  ovides implement
23e80 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65  ations for these
23e90 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69   routines when i
23ea0 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  t is compiled.**
23eb0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
23ec0 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20 45 78  _DEBUG flag.  Ex
23ed0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70  ternal mutex imp
23ee0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
23ef0 61 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65  are only require
23f00 64 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65  d to provide the
23f10 73 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53  se routines if S
23f20 51 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a  QLITE_DEBUG is.*
23f30 2a 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66  * defined and if
23f40 20 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64   NDEBUG is not d
23f50 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
23f60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  ese routines sho
23f70 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20  uld return true 
23f80 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20  if the mutex in 
23f90 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a  their argument.*
23fa0 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74  * is held or not
23fb0 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76   held, respectiv
23fc0 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c  ely, by the call
23fd0 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  ing thread..**.*
23fe0 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * The implementa
23ff0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75  tion is not requ
24000 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64  ired to provided
24010 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65   versions of the
24020 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  se.** routines t
24030 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72  hat actually wor
24040 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6d 70  k..** If the imp
24050 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73  lementation does
24060 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72   not provide wor
24070 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  king.** versions
24080 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
24090 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74  es, it should at
240a0 20 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73   least provide s
240b0 74 75 62 73 0a 2a 2a 20 74 68 61 74 20 61 6c 77  tubs.** that alw
240c0 61 79 73 20 72 65 74 75 72 6e 20 74 72 75 65 20  ays return true 
240d0 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73  so that one does
240e0 20 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75   not get spuriou
240f0 73 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e 20 66  s.** assertion f
24100 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  ailures..**.** I
24110 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  f the argument t
24120 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
24130 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c  held() is a NULL
24140 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
24150 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f   the routine sho
24160 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 54  uld return 1.  T
24170 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65  his seems counte
24180 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63  r-intuitive sinc
24190 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65  e.** clearly the
241a0 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65   mutex cannot be
241b0 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73   held if it does
241c0 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74   not exist.  But
241d0 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73   the.** the reas
241e0 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65  on the mutex doe
241f0 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62  s not exist is b
24200 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64  ecause the build
24210 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67   is not.** using
24220 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77   mutexes.  And w
24230 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68  e do not want th
24240 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61  e assert() conta
24250 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c  ining the.** cal
24260 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  l to sqlite3_mut
24270 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69  ex_held() to fai
24280 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f  l, so a non-zero
24290 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68   return is.** th
242a0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68  e appropriate th
242b0 69 6e 67 20 74 6f 20 64 6f 2e 20 20 54 68 65 20  ing to do.  The 
242c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
242d0 74 68 65 6c 64 28 29 20 0a 2a 2a 20 69 6e 74 65  theld() .** inte
242e0 72 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73  rface should als
242f0 6f 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20  o return 1 when 
24300 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  given a NULL poi
24310 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nter..*/.int sql
24320 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
24330 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
24340 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
24350 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74  ex_notheld(sqlit
24360 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a  e3_mutex*);../*.
24370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
24380 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54  ex Types.**.** T
24390 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
243a0 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72  x_alloc()] inter
243b0 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e  face takes a sin
243c0 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  gle argument.** 
243d0 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20  which is one of 
243e0 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  these integer co
243f0 6e 73 74 61 6e 74 73 2e 0a 2a 2f 0a 23 64 65 66  nstants..*/.#def
24400 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
24410 5f 46 41 53 54 20 20 20 20 20 20 20 20 20 20 20  _FAST           
24420 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
24430 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
24440 56 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  VE        1.#def
24450 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
24460 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20  _STATIC_MASTER  
24470 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
24480 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
24490 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20  MEM       3  /* 
244a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
244b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
244c0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
244d0 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20  MEM2      4  /* 
244e0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
244f0 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a 23 64 65 66  memory() */.#def
24500 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
24510 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20  _STATIC_PRNG    
24520 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
24530 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66  random() */.#def
24540 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
24550 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20  _STATIC_LRU     
24560 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65    6  /* lru page
24570 20 6c 69 73 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   list */.../*.**
24580 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74   Undo the hack t
24590 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f  hat converts flo
245a0 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65  ating point type
245b0 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72  s to integer for
245c0 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72  .** builds on pr
245d0 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74  ocessors without
245e0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
245f0 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64  support..*/.#ifd
24600 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
24610 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
24620 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e  undef double.#en
24630 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70  dif..#ifdef __cp
24640 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e  lusplus.}  /* En
24650 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e  d of the 'extern
24660 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23   "C"' block */.#
24670 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a           endif.#endif.