/ Hex Artifact Content
Login

Artifact 1ef41c05bf64d580e77e6c57f8705cdf36f37be0:


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 37 20 32 30 30 37 2f  in,v 1.247 2007/
05f0: 30 38 2f 32 39 20 31 32 3a 33 31 3a 32 38 20 64  08/29 12:31:28 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 5b 73  lled.  So the [s
5b30: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
5b40: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
5b50: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
5b60: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
5b70: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
5b80: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
5b90: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  e reason..**.** 
5ba0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
5bb0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 73  nt to xOpen() is
5bc0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
5bd0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  lags argument.**
5be0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
5bf0: 5f 76 32 28 29 2e 20 20 49 66 20 73 71 6c 69 74  _v2().  If sqlit
5c00: 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
5c10: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 0a 2a 2a  ite3_open16().**
5c20: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
5c30: 6c 61 67 73 20 69 73 20 53 51 4c 49 54 45 5f 4f  lags is SQLITE_O
5c40: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 7c 20  PEN_READWRITE | 
5c50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
5c60: 54 45 2e 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  TE..** If xOpen(
5c70: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
5c80: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
5c90: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
5ca0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 53   to.** include S
5cb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5cc0: 4e 4c 59 2e 20 20 4f 74 68 65 72 20 62 69 74 73  NLY.  Other bits
5cd0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
5ce0: 61 79 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a  ay be.** set..**
5cf0: 20 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c   .** SQLite will
5d00: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
5d10: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
5d20: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
5d30: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
5d40: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
5d50: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
5d60: 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  d:.** .** <ul>.*
5d70: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
5d80: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
5d90: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
5da0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
5db0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
5dc0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
5dd0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
5de0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5df0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
5e00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
5e10: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
5e20: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
5e30: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
5e40: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
5e50: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
5e60: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
5e70: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
5e80: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
5e90: 67 65 73 20 74 68 65 20 77 61 79 20 69 74 20 64  ges the way it d
5ea0: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
5eb0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
5ec0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
5ed0: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
5ee0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
5ef0: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
5f00: 62 61 63 6b 2c 20 6d 69 67 68 74 20 6d 61 6b 65  back, might make
5f10: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
5f20: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
5f30: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
5f40: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
5f50: 61 72 65 0a 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f  are.** also a no
5f60: 2d 6f 70 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  -op.  Any attemp
5f70: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
5f80: 75 72 6e 61 6c 20 72 65 74 75 72 6e 20 53 51 4c  urnal return SQL
5f90: 49 54 45 5f 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72  ITE_IOERR..** Or
5fa0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
5fb0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
5fc0: 69 7a 65 20 74 68 65 20 61 20 64 61 74 61 62 61  ize the a databa
5fd0: 73 65 20 66 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20  se file will.** 
5fe0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
5ff0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
6000: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
6010: 20 61 20 72 61 6e 64 6f 6d 20 6f 72 64 65 72 0a   a random order.
6020: 2a 2a 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  ** and set up it
6030: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
6040: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20  accordingly..** 
6050: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
6060: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
6070: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
6080: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
6090: 6e 0a 2a 2a 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20  n.** method:.** 
60a0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
60b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
60c0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
60d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
60e0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
60f0: 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  </ul>.** .** The
6100: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
6110: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
6120: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
6130: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
6140: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
6150: 20 63 6c 6f 73 65 64 2e 20 20 54 68 69 73 20 77   closed.  This w
6160: 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 73 65  ill always be se
6170: 74 20 66 6f 72 20 54 45 4d 50 20 0a 2a 2a 20 64  t for TEMP .** d
6180: 61 74 61 62 61 73 65 73 20 61 6e 64 20 6a 6f 75  atabases and jou
6190: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
61a0: 62 6a 6f 75 72 6e 61 6c 73 2e 20 20 54 68 65 20  bjournals.  The 
61b0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
61c0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
61d0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
61e0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
61f0: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
6200: 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73 20  e access.  This 
6210: 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72 20  flag is set for 
6220: 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74  all files except
6230: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e  .** for the main
6240: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
6250: 2a 2a 20 0a 2a 2a 20 53 70 61 63 65 20 74 6f 20  ** .** Space to 
6260: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
6270: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
6280: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
6290: 20 74 68 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d   third .** argum
62a0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ent to xOpen is 
62b0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 63 61 6c  allocated by cal
62c0: 6c 65 72 20 28 74 68 65 20 53 51 4c 69 74 65 20  ler (the SQLite 
62d0: 63 6f 72 65 29 2e 20 0a 2a 2a 20 73 7a 4f 73 46  core). .** szOsF
62e0: 69 6c 65 20 62 79 74 65 73 20 61 72 65 20 61 6c  ile bytes are al
62f0: 6c 6f 63 61 74 65 64 20 66 6f 72 20 74 68 69 73  located for this
6300: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 78 4f   object.  The xO
6310: 70 65 6e 20 6d 65 74 68 6f 64 0a 2a 2a 20 66 69  pen method.** fi
6320: 6c 6c 73 20 69 6e 20 74 68 65 20 61 6c 6c 6f 63  lls in the alloc
6330: 61 74 65 64 20 73 70 61 63 65 2e 0a 2a 2a 20 0a  ated space..** .
6340: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
6350: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
6360: 28 29 20 6d 61 79 20 62 65 20 30 20 28 74 6f 20  () may be 0 (to 
6370: 74 65 73 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20  test for the.** 
6380: 65 78 69 73 74 61 6e 63 65 20 6f 66 20 61 20 66  existance of a f
6390: 69 6c 65 29 20 6f 72 20 53 51 4c 49 54 45 5f 41  ile) or SQLITE_A
63a0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
63b0: 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65 0a 2a  to test to see.*
63c0: 2a 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 72  * if a file is r
63d0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
63e0: 61 62 6c 65 2c 20 6f 72 20 53 51 4c 49 54 45 5f  able, or SQLITE_
63f0: 41 43 43 45 53 53 5f 52 45 41 44 4f 4e 4c 59 0a  ACCESS_READONLY.
6400: 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65  ** to test to se
6410: 65 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 72  e if a file is r
6420: 65 61 64 2d 6f 6e 6c 79 2e 20 20 54 68 65 20 66  ead-only.  The f
6430: 69 6c 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a  ile can be a .**
6440: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a   directory..** .
6450: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  ** SQLite will a
6460: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
6470: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
6480: 6d 65 2b 31 20 62 79 74 65 20 66 6f 72 0a 2a 2a  me+1 byte for.**
6490: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
64a0: 65 72 73 20 66 6f 72 20 78 47 65 74 54 65 6d 70  ers for xGetTemp
64b0: 4e 61 6d 65 20 61 6e 64 20 78 46 75 6c 6c 50 61  Name and xFullPa
64c0: 74 68 6e 61 6d 65 2e 0a 2a 2a 20 0a 2a 2a 20 54  thname..** .** T
64d0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
64e0: 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20  , xSleep(), and 
64f0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
6500: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65  nterfaces.** are
6510: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
6520: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
6530: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
6540: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
6550: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
6560: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
6570: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
6580: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
6590: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
65a0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
65b0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
65c0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
65d0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
65e0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
65f0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
6600: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
6610: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
6620: 67 65 6e 65 72 61 74 65 64 2e 20 20 54 68 65 0a  generated.  The.
6630: 2a 2a 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  ** xSleep() meth
6640: 6f 64 20 63 61 75 73 65 20 74 68 65 20 63 61 6c  od cause the cal
6650: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
6660: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
6670: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
6680: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
6690: 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72  given.  The xCur
66a0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
66b0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
66c0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
66d0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
66e0: 20 64 61 74 65 20 61 6e 64 0a 2a 2a 20 74 69 6d   date and.** tim
66f0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
6700: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
6710: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74   sqlite3_vfs;.st
6720: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
6730: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
6740: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
6750: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
6760: 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69  on number */.  i
6770: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
6780: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
6790: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
67a0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
67b0: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
67c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
67d0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
67e0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
67f0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
6800: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
6810: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
6820: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
6830: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
6840: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
6850: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
6860: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
6870: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
6880: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
6890: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
68a0: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
68b0: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
68c0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
68d0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
68e0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
68f0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
6900: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
6910: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
6920: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
6930: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
6940: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
6950: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
6960: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
6970: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
6980: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  ame, int flags);
6990: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 54 65 6d  .  int (*xGetTem
69a0: 70 4e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  pName)(sqlite3_v
69b0: 66 73 2a 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  fs*, char *zOut)
69c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
69d0: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
69e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
69f0: 72 20 2a 7a 4e 61 6d 65 2c 20 63 68 61 72 20 2a  r *zName, char *
6a00: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
6a10: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
6a20: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
6a30: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
6a40: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
6a50: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
6a60: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
6a70: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
6a80: 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  id *(*xDlSym)(sq
6a90: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
6aa0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
6ab0: 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28  ymbol);.  void (
6ac0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
6ad0: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
6ae0: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
6af0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
6b00: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
6b10: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
6b20: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
6b30: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
6b40: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
6b50: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
6b60: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
6b70: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20   double*);.  /* 
6b80: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
6b90: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
6ba0: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
6bb0: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
6bc0: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
6bd0: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
6be0: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f  this happens. */
6bf0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
6c00: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
6c10: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
6c20: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
6c30: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
6c40: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
6c50: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
6c60: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
6c70: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
6c80: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
6c90: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
6ca0: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74  y determine.** t
6cb0: 68 65 20 6b 69 6e 64 20 6f 66 20 77 68 61 74 20  he kind of what 
6cc0: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
6cd0: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
6ce0: 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20 6c 6f 6f  method is.** loo
6cf0: 6b 69 6e 67 20 66 6f 72 2e 20 20 57 69 74 68 20  king for.  With 
6d00: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
6d10: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
6d20: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
6d30: 6c 79 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65  ly checks to see
6d40: 20 69 66 20 74 68 65 20 66 69 6c 65 20 65 78 69   if the file exi
6d50: 73 74 73 2e 20 20 57 69 74 68 20 53 51 4c 49 54  sts.  With SQLIT
6d60: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
6d70: 54 45 2c 0a 2a 2a 20 74 68 65 20 78 41 63 63 65  TE,.** the xAcce
6d80: 73 73 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  ss method checks
6d90: 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 66   to see if the f
6da0: 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64  ile is both read
6db0: 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 77 72 69 74  able.** and writ
6dc0: 61 62 6c 65 2e 20 20 57 69 74 68 20 53 51 4c 49  able.  With SQLI
6dd0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 74  TE_ACCESS_READ t
6de0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
6df0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 74 6f 20 73  d.** checks to s
6e00: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ee if the file i
6e10: 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23  s readable..*/.#
6e20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
6e30: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
6e40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6e50: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
6e60: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6e70: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
6e80: 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     2../*.** CAPI
6e90: 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
6ea0: 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
6eb0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
6ec0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
6ed0: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
6ee0: 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  bles the.** [SQL
6ef0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
6f00: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
6f10: 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 2e   codes] feature.
6f20: 0a 2a 2a 20 42 79 20 64 65 66 61 75 6c 74 2c 20  .** By default, 
6f30: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
6f40: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
6f50: 66 20 6f 6e 6c 79 20 32 36 20 69 6e 74 65 67 65  f only 26 intege
6f60: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  r.** [SQLITE_OK 
6f70: 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e  | result codes].
6f80: 20 20 57 68 65 6e 20 65 78 74 65 6e 64 65 64 20    When extended 
6f90: 72 65 73 75 6c 74 20 63 6f 64 65 73 0a 2a 2a 20  result codes.** 
6fa0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 74  are enabled by t
6fb0: 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 65  his routine, the
6fc0: 20 72 65 70 65 74 6f 69 72 65 20 6f 66 20 72 65   repetoire of re
6fd0: 73 75 6c 74 20 63 6f 64 65 73 20 63 61 6e 20 62  sult codes can b
6fe0: 65 0a 2a 2a 20 6d 75 63 68 20 6c 61 72 67 65 72  e.** much larger
6ff0: 20 61 6e 64 20 63 61 6e 20 28 68 6f 70 65 66 75   and can (hopefu
7000: 6c 6c 79 29 20 70 72 6f 76 69 64 65 20 6d 6f 72  lly) provide mor
7010: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
7020: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
7030: 74 68 65 20 63 61 75 73 65 20 6f 66 20 61 6e 20  the cause of an 
7040: 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
7050: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
7060: 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61   is a boolean va
7070: 6c 75 65 20 74 68 61 74 20 74 75 72 6e 73 20 65  lue that turns e
7080: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
7090: 2a 20 63 6f 64 65 73 20 6f 6e 20 61 6e 64 20 6f  * codes on and o
70a0: 66 66 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65  ff.  Extended re
70b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6f  sult codes are o
70c0: 66 66 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ff by default fo
70d0: 72 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  r.** backwards c
70e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
70f0: 68 20 6f 6c 64 65 72 20 76 65 72 73 69 6f 6e 73  h older versions
7100: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
7110: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
7120: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
7130: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
7140: 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
7150: 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
7160: 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
7170: 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
7180: 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
7190: 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
71a0: 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
71b0: 20 6b 65 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 74   key.** called t
71c0: 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20  he "rowid". The 
71d0: 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
71e0: 61 76 61 69 6c 61 62 6c 65 20 61 73 20 61 6e 20  available as an 
71f0: 75 6e 64 65 63 6c 61 72 65 64 0a 2a 2a 20 63 6f  undeclared.** co
7200: 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
7210: 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
7220: 5f 2e 20 20 49 66 20 74 68 65 20 74 61 62 6c 65  _.  If the table
7230: 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
7240: 0a 2a 2a 20 74 79 70 65 20 49 4e 54 45 47 45 52  .** type INTEGER
7250: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65   PRIMARY KEY the
7260: 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
7270: 20 61 6e 6f 74 68 65 72 20 61 6e 20 61 6c 69 61   another an alia
7280: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 72 6f 77  s for the.** row
7290: 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  id..**.** This r
72a0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
72b0: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
72c0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
72d0: 52 54 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 64  RT into.** the d
72e0: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
72f0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7300: 74 69 6f 6e 20 67 69 76 65 6e 20 69 6e 20 74 68  tion given in th
7310: 65 20 66 69 72 73 74 20 0a 2a 2a 20 61 72 67 75  e first .** argu
7320: 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 69 6e 73  ment.  If no ins
7330: 65 72 74 73 20 68 61 76 65 20 65 76 65 72 20 6f  erts have ever o
7340: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 69 73 20  ccurred on this 
7350: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
7360: 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
7370: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
7380: 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63  If an INSERT occ
7390: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
73a0: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  gger, then the r
73b0: 6f 77 69 64 20 6f 66 20 74 68 65 0a 2a 2a 20 69  owid of the.** i
73c0: 6e 73 65 72 74 65 64 20 72 6f 77 20 69 73 20 72  nserted row is r
73d0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
73e0: 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20  routine as long 
73f0: 61 73 20 74 68 65 20 74 72 69 67 67 65 72 0a 2a  as the trigger.*
7400: 2a 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 42  * is running.  B
7410: 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
7420: 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20  ger terminates, 
7430: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
7440: 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  ed.** by this ro
7450: 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
7460: 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20   the last value 
7470: 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20  inserted before 
7480: 74 68 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 66  the.** trigger f
7490: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ired..**.** If a
74a0: 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 64 6f  nother thread do
74b0: 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72 74 20  es a new insert 
74c0: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
74d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
74e0: 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  ** while this ro
74f0: 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
7500: 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
7510: 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
7520: 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 74 68 65 6e  t rowid,.** then
7530: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
7540: 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
7550: 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e is undefined..
7560: 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
7570: 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
7580: 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
7590: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
75a0: 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
75b0: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
75c0: 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 54  Modified.**.** T
75d0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
75e0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
75f0: 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
7600: 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
7610: 65 64 0a 2a 2a 20 28 6f 72 20 69 6e 73 65 72 74  ed.** (or insert
7620: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 29 20 62  ed or deleted) b
7630: 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
7640: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  t SQL statement.
7650: 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 65    Only.** change
7660: 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
7670: 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
7680: 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
7690: 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 54  ATE, or.** DELET
76a0: 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  E statement are 
76b0: 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
76c0: 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
76d0: 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
76e0: 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  s are not counte
76f0: 64 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c  d.  Use the [sql
7700: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
7710: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
7720: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
7730: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
7740: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
7750: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
7760: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
7770: 2a 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  * Within the bod
7780: 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 20  y of a trigger, 
7790: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
77a0: 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
77b0: 63 61 6e 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  can be.** called
77c0: 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
77d0: 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
77e0: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
77f0: 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
7800: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
7810: 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
7820: 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
7830: 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 74  he body of the t
7840: 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 6c  rigger..**.** Al
7850: 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  l changes are co
7860: 75 6e 74 65 64 2c 20 65 76 65 6e 20 69 66 20 74  unted, even if t
7870: 68 65 79 20 77 65 72 65 20 6c 61 74 65 72 20 75  hey were later u
7880: 6e 64 6f 6e 65 20 62 79 20 61 0a 2a 2a 20 52 4f  ndone by a.** RO
7890: 4c 4c 42 41 43 4b 20 6f 72 20 41 42 4f 52 54 2e  LLBACK or ABORT.
78a0: 20 20 45 78 63 65 70 74 2c 20 63 68 61 6e 67 65    Except, change
78b0: 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
78c0: 68 20 63 72 65 61 74 69 6e 67 20 61 6e 64 0a 2a  h creating and.*
78d0: 2a 20 64 72 6f 70 70 69 6e 67 20 74 61 62 6c 65  * dropping table
78e0: 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  s are not counte
78f0: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61  d..**.** If a ca
7900: 6c 6c 62 61 63 6b 20 69 6e 76 6f 6b 65 73 20 5b  llback invokes [
7910: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
7920: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
7930: 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 2c  ()] recursively,
7940: 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 68 61  .** then the cha
7950: 6e 67 65 73 20 69 6e 20 74 68 65 20 69 6e 6e 65  nges in the inne
7960: 72 2c 20 72 65 63 75 72 73 69 76 65 20 63 61 6c  r, recursive cal
7970: 6c 20 61 72 65 20 63 6f 75 6e 74 65 64 20 74 6f  l are counted to
7980: 67 65 74 68 65 72 0a 2a 2a 20 77 69 74 68 20 74  gether.** with t
7990: 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  he changes in th
79a0: 65 20 6f 75 74 65 72 20 63 61 6c 6c 2e 0a 2a 2a  e outer call..**
79b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
79c0: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
79d0: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
79e0: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20  able" without a 
79f0: 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20  WHERE clause.** 
7a00: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
7a10: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
7a20: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
7a30: 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e  much faster than
7a40: 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67   going.** throug
7a50: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
7a60: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
7a70: 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c  ts from the tabl
7a80: 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a  e.)  Because of.
7a90: 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61  ** this optimiza
7aa0: 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65  tion, the change
7ab0: 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45   count for "DELE
7ac0: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
7ad0: 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72  ill be.** zero r
7ae0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
7af0: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
7b00: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
7b10: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a  iginally in the.
7b20: 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74  ** table. To get
7b30: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
7b40: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
7b50: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
7b60: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
7b70: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
7b80: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a  E 1" instead..**
7b90: 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
7ba0: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
7bb0: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
7bc0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7bd0: 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69  ion.** while thi
7be0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
7bf0: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 72 65  ning then the re
7c00: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
7c10: 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73  is routine.** is
7c20: 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69   undefined..*/.i
7c30: 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
7c40: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
7c50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
7c60: 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
7c70: 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 2a  ows Modified.***
7c80: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
7c90: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
7ca0: 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
7cb0: 20 72 6f 77 73 20 74 68 61 74 20 68 61 76 65 20   rows that have 
7cc0: 62 65 65 6e 0a 2a 2a 20 6d 6f 64 69 66 69 65 64  been.** modified
7cd0: 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41   by INSERT, UPDA
7ce0: 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
7cf0: 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
7d00: 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
7d10: 65 0a 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e  e.** was opened.
7d20: 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 55   This includes U
7d30: 50 44 41 54 45 2c 20 49 4e 53 45 52 54 20 61 6e  PDATE, INSERT an
7d40: 64 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  d DELETE stateme
7d50: 6e 74 73 20 65 78 65 63 75 74 65 64 0a 2a 2a 20  nts executed.** 
7d60: 61 73 20 70 61 72 74 20 6f 66 20 74 72 69 67 67  as part of trigg
7d70: 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 41 6c 6c  er programs. All
7d80: 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
7d90: 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  nted as soon as 
7da0: 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
7db0: 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
7dc0: 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
7dd0: 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
7de0: 74 20 68 61 6e 64 6c 65 20 69 73 0a 2a 2a 20 70  t handle is.** p
7df0: 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
7e00: 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
7e10: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 73 65 28  qlite3_finalise(
7e20: 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
7e30: 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
7e40: 5f 63 68 61 6e 67 65 28 29 5d 20 69 6e 74 65 72  _change()] inter
7e50: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  face..**.** SQLi
7e60: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
7e70: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
7e80: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
7e90: 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c  thout a WHERE cl
7ea0: 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70  ause.** by dropp
7eb0: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
7ec0: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
7ed0: 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73  This is much fas
7ee0: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a  ter than going.*
7ef0: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65  * through and de
7f00: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61  leting individua
7f10: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72 6d 20  l elements form 
7f20: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63  the table.)  Bec
7f30: 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20  ause of.** this 
7f40: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
7f50: 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66  e change count f
7f60: 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  or "DELETE FROM 
7f70: 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a  table" will be.*
7f80: 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73  * zero regardles
7f90: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  s of the number 
7fa0: 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74  of elements that
7fb0: 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79   were originally
7fc0: 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65   in the.** table
7fd0: 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75  . To get an accu
7fe0: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68  rate count of th
7ff0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
8000: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a   deleted, use.**
8010: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
8020: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73  ble WHERE 1" ins
8030: 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tead..**.** If a
8040: 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d 61  nother thread ma
8050: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
8060: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
8070: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
8080: 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
8090: 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  e is running the
80a0: 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
80b0: 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ue of this routi
80c0: 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ne.** is undefin
80d0: 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
80e0: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
80f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
8100: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
8110: 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
8120: 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
8130: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
8140: 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
8150: 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
8160: 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
8170: 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
8180: 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
8190: 6f 72 74 75 6e 69 74 79 2e 20 20 54 68 69 73 20  ortunity.  This 
81a0: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
81b0: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
81c0: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
81d0: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
81e0: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
81f0: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
8200: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
8210: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
8220: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
8230: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
8240: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
8250: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
8260: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
8270: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
8280: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
8290: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
82a0: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
82b0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
82c0: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
82d0: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
82e0: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
82f0: 75 74 69 6e 65 20 77 69 74 68 20 61 20 64 61 74  utine with a dat
8300: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8310: 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
8320: 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
8330: 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
8340: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
8350: 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
8360: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
8370: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
8380: 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
8390: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
83a0: 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  ..** If an inter
83b0: 72 75 70 74 65 64 20 6f 70 65 72 61 74 69 6f 6e  rupted operation
83c0: 20 77 61 73 20 61 6e 20 75 70 64 61 74 65 20 74   was an update t
83d0: 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
83e0: 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
83f0: 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
8400: 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
8410: 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72 6f  ction will be ro
8420: 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 61 75 74  lled.** back aut
8430: 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2f 0a 76  omatically..*/.v
8440: 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
8450: 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
8460: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
8470: 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
8480: 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
8490: 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
84a0: 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
84b0: 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  s return true if
84c0: 20 74 68 65 20 67 69 76 65 6e 20 69 6e 70 75 74   the given input
84d0: 20 73 74 72 69 6e 67 20 63 6f 6d 70 72 69 73 65   string comprise
84e0: 73 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  s.** one or more
84f0: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
8500: 61 74 65 6d 65 6e 74 73 2e 20 46 6f 72 20 74 68  atements. For th
8510: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  e sqlite3_comple
8520: 74 65 28 29 20 63 61 6c 6c 2c 0a 2a 2a 20 74 68  te() call,.** th
8530: 65 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  e parameter must
8540: 20 62 65 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   be a nul-termin
8550: 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
8560: 67 2e 20 46 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  g. For.** sqlite
8570: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2c 20  3_complete16(), 
8580: 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
8590: 20 6d 61 63 68 69 6e 65 20 62 79 74 65 20 6f 72   machine byte or
85a0: 64 65 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e  der UTF-16 strin
85b0: 67 0a 2a 2a 20 69 73 20 72 65 71 75 69 72 65 64  g.** is required
85c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
85d0: 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
85e0: 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69  l for command-li
85f0: 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
8600: 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
8610: 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
8620: 64 20 74 65 78 74 20 66 6f 72 6d 73 20 6f 6e 65  d text forms one
8630: 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 74   or more complet
8640: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
8650: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
8660: 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
8670: 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
8680: 69 6e 67 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ing the statemen
8690: 74 73 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  ts into.** SQLit
86a0: 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 54  e for parsing. T
86b0: 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73 20  he algorithm is 
86c0: 73 69 6d 70 6c 65 2e 20 20 49 66 20 74 68 65 20  simple.  If the 
86d0: 0a 2a 2a 20 6c 61 73 74 20 74 6f 6b 65 6e 20 6f  .** last token o
86e0: 74 68 65 72 20 74 68 61 6e 20 73 70 61 63 65 73  ther than spaces
86f0: 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 69 73   and comments is
8700: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2c 20 74 68   a semicolon, th
8710: 65 6e 20 72 65 74 75 72 6e 20 0a 2a 2a 20 74 72  en return .** tr
8720: 75 65 2e 20 20 41 63 74 75 61 6c 6c 79 2c 20 74  ue.  Actually, t
8730: 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73 20  he algorithm is 
8740: 61 20 6c 69 74 74 6c 65 20 6d 6f 72 65 20 63 6f  a little more co
8750: 6d 70 6c 69 63 61 74 65 64 20 74 68 61 6e 20 74  mplicated than t
8760: 68 61 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  hat.** in order 
8770: 74 6f 20 64 65 61 6c 20 77 69 74 68 20 74 72 69  to deal with tri
8780: 67 67 65 72 73 2c 20 62 75 74 20 74 68 65 20 62  ggers, but the b
8790: 61 73 69 63 20 69 64 65 61 20 69 73 20 74 68 65  asic idea is the
87a0: 20 73 61 6d 65 3a 20 20 74 68 65 0a 2a 2a 20 73   same:  the.** s
87b0: 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
87c0: 63 6f 6d 70 6c 65 74 65 20 75 6e 6c 65 73 73 20  complete unless 
87d0: 69 74 20 65 6e 64 73 20 69 6e 20 61 20 73 65 6d  it ends in a sem
87e0: 69 63 6f 6c 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  icolon..*/.int s
87f0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
8800: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
8810: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
8820: 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
8830: 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
8840: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
8850: 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
8860: 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
8870: 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a  _BUSY Errors.**.
8880: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
8890: 69 64 65 6e 74 69 66 69 65 73 20 61 20 63 61 6c  identifies a cal
88a0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
88b0: 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
88c0: 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65 72  oked.** whenever
88d0: 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
88e0: 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
88f0: 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a 2a  tabase table .**
8900: 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
8910: 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73 20  read or process 
8920: 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49  has locked..** I
8930: 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
8940: 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
8950: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
8960: 2a 2a 20 28 6f 72 20 73 6f 6d 65 74 69 6d 65 73  ** (or sometimes
8970: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
8980: 4c 4f 43 4b 45 44 5d 29 0a 2a 2a 20 69 73 20 72  LOCKED]).** is r
8990: 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
89a0: 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
89b0: 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 0a  ering the lock..
89c0: 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63  ** If the busy c
89d0: 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 4e  allback is not N
89e0: 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ULL, then the.**
89f0: 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62   callback will b
8a00: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
8a10: 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  wo arguments.  T
8a20: 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75  he.** first argu
8a30: 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64  ment to the hand
8a40: 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
8a50: 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
8a60: 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
8a70: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
8a80: 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  t to this routin
8a90: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  e.  The second a
8aa0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
8ab0: 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68 65  e handler is the
8ac0: 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
8ad0: 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
8ae0: 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
8af0: 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
8b00: 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
8b10: 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73  t. If the.** bus
8b20: 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
8b30: 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
8b40: 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
8b50: 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
8b60: 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
8b70: 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
8b80: 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
8b90: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
8ba0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
8bb0: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
8bc0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
8bd0: 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
8be0: 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
8bf0: 74 6f 20 6f 70 65 6e 20 74 68 65 0a 2a 2a 20 64  to open the.** d
8c00: 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
8c10: 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
8c20: 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
8c30: 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
8c40: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
8c50: 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
8c60: 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20 77 69  ee that.** it wi
8c70: 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ll be invoked wh
8c80: 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
8c90: 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20   contention..** 
8ca0: 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
8cb0: 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
8cc0: 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
8cd0: 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
8ce0: 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63   in.** a deadloc
8cf0: 6b 2c 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  k, it will retur
8d00: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
8d10: 69 6e 73 74 65 61 64 2e 0a 2a 2a 20 43 6f 6e 73  instead..** Cons
8d20: 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
8d30: 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
8d40: 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
8d50: 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
8d60: 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
8d70: 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
8d80: 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
8d90: 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
8da0: 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
8db0: 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
8dc0: 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
8dd0: 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
8de0: 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
8df0: 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
8e00: 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
8e10: 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
8e20: 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
8e30: 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
8e40: 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
8e50: 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
8e60: 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
8e70: 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
8e80: 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
8e90: 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
8ea0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
8eb0: 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
8ec0: 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
8ed0: 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
8ee0: 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
8ef0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
8f00: 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
8f10: 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
8f20: 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
8f30: 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
8f40: 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
8f50: 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
8f60: 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
8f70: 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
8f80: 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
8f90: 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  eed..**.** The d
8fa0: 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
8fb0: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
8fc0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8fd0: 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
8fe0: 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
8ff0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
9000: 44 5d 20 77 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  D] when.** SQLit
9010: 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
9020: 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
9030: 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
9040: 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
9050: 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
9060: 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
9070: 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
9080: 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
9090: 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
90a0: 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
90b0: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
90c0: 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
90d0: 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
90e0: 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
90f0: 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
9100: 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
9110: 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
9120: 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
9130: 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
9140: 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
9150: 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c    If it is unabl
9160: 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
9170: 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
9180: 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
9190: 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
91a0: 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
91b0: 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
91c0: 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
91d0: 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
91e0: 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
91f0: 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
9200: 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
9210: 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
9220: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
9230: 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72  ED].  This error
9240: 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
9250: 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
9260: 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
9270: 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
9280: 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
9290: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73  ef="http://www.s
92a0: 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 61  qlite.org/cvstra
92b0: 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
92c0: 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
92d0: 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
92e0: 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
92f0: 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
9300: 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
9310: 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
9320: 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
9330: 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 53 71 6c 69 74  nt..**..** Sqlit
9340: 65 20 69 73 20 72 65 2d 65 6e 74 72 61 6e 74 2c  e is re-entrant,
9350: 20 73 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   so the busy han
9360: 64 6c 65 72 20 6d 61 79 20 73 74 61 72 74 20 61  dler may start a
9370: 20 6e 65 77 20 71 75 65 72 79 2e 20 0a 2a 2a 20   new query. .** 
9380: 28 49 74 20 69 73 20 6e 6f 74 20 63 6c 65 61 72  (It is not clear
9390: 20 77 68 79 20 61 6e 79 6f 6e 65 20 77 6f 75 6c   why anyone woul
93a0: 64 20 65 76 65 72 79 20 77 61 6e 74 20 74 6f 20  d every want to 
93b0: 64 6f 20 74 68 69 73 2c 20 62 75 74 20 69 74 0a  do this, but it.
93c0: 2a 2a 20 69 73 20 61 6c 6c 6f 77 65 64 2c 20 69  ** is allowed, i
93d0: 6e 20 74 68 65 6f 72 79 2e 29 20 20 42 75 74 20  n theory.)  But 
93e0: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
93f0: 20 6d 61 79 20 6e 6f 74 20 63 6c 6f 73 65 20 74   may not close t
9400: 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
9410: 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 64 61 74   Closing the dat
9420: 61 62 61 73 65 20 66 72 6f 6d 20 61 20 62 75 73  abase from a bus
9430: 79 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 64  y handler will d
9440: 65 6c 65 74 65 20 0a 2a 2a 20 64 61 74 61 20 73  elete .** data s
9450: 74 72 75 63 74 75 72 65 73 20 6f 75 74 20 66 72  tructures out fr
9460: 6f 6d 20 75 6e 64 65 72 20 74 68 65 20 65 78 65  om under the exe
9470: 63 75 74 69 6e 67 20 71 75 65 72 79 20 61 6e 64  cuting query and
9480: 20 77 69 6c 6c 20 0a 2a 2a 20 70 72 6f 62 61 62   will .** probab
9490: 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ly result in a s
94a0: 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
94b0: 74 20 6f 72 20 6f 74 68 65 72 20 72 75 6e 74 69  t or other runti
94c0: 6d 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  me error..**.** 
94d0: 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
94e0: 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
94f0: 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
9500: 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73  for each databas
9510: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9520: 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
9530: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
9540: 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ars any previous
9550: 20 6f 6e 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68   one..** Note th
9560: 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
9570: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
9580: 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  ()] will also se
9590: 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74 68  t or clear.** th
95a0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
95b0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 6f 70 65 72 61  **.** When opera
95c0: 74 69 6e 67 20 69 6e 20 5b 73 71 6c 69 74 65 33  ting in [sqlite3
95d0: 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
95e0: 61 63 68 65 20 7c 20 73 68 61 72 65 64 20 63 61  ache | shared ca
95f0: 63 68 65 20 6d 6f 64 65 5d 2c 0a 2a 2a 20 6f 6e  che mode],.** on
9600: 6c 79 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  ly a single busy
9610: 20 68 61 6e 64 6c 65 72 20 63 61 6e 20 62 65 20   handler can be 
9620: 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
9630: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
9640: 2a 2a 20 53 6f 20 69 66 20 74 77 6f 20 64 61 74  ** So if two dat
9650: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9660: 73 20 73 68 61 72 65 20 61 20 73 69 6e 67 6c 65  s share a single
9670: 20 63 61 63 68 65 2c 20 74 68 65 6e 20 63 68 61   cache, then cha
9680: 6e 67 69 6e 67 0a 2a 2a 20 74 68 65 20 62 75 73  nging.** the bus
9690: 79 20 68 61 6e 64 6c 65 72 20 6f 6e 20 6f 6e 65  y handler on one
96a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69 6c 6c   connection will
96b0: 20 61 6c 73 6f 20 63 68 61 6e 67 65 20 74 68 65   also change the
96c0: 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
96d0: 20 69 6e 20 74 68 65 20 6f 74 68 65 72 20 63 6f   in the other co
96e0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 62  nnection.  The b
96f0: 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 69  usy handler is i
9700: 6e 76 6f 6b 65 64 0a 2a 2a 20 69 6e 20 74 68 65  nvoked.** in the
9710: 20 74 68 72 65 61 64 20 74 68 61 74 20 77 61 73   thread that was
9720: 20 72 75 6e 6e 69 6e 67 20 77 68 65 6e 20 74 68   running when th
9730: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 77 61  e SQLITE_BUSY wa
9740: 73 20 68 69 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  s hit..*/.int sq
9750: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
9760: 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
9770: 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
9780: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
9790: 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
97a0: 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
97b0: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  * This routine s
97c0: 65 74 73 20 61 20 62 75 73 79 20 68 61 6e 64 6c  ets a busy handl
97d0: 65 72 20 74 68 61 74 20 73 6c 65 65 70 73 20 66  er that sleeps f
97e0: 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65 6e 20  or a while when 
97f0: 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c 6f  a.** table is lo
9800: 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c  cked.  The handl
9810: 65 72 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  er will sleep mu
9820: 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
9830: 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74 20  il .** at least 
9840: 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
9850: 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68 61  s of sleeping ha
9860: 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 20 41  ve been done.  A
9870: 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c  fter.** "ms" mil
9880: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
9890: 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e 64 6c  eping, the handl
98a0: 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
98b0: 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73 71  ch.** causes [sq
98c0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
98d0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
98e0: 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
98f0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
9900: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74  .**.** Calling t
9910: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
9920: 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
9930: 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
9940: 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
9950: 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
9960: 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ndlers..**.** Th
9970: 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
9980: 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
9990: 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
99a0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
99b0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
99c0: 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
99d0: 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65 66 69  handler was defi
99e0: 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e 67 20  ned  .** (using 
99f0: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
9a00: 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
9a10: 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
9a20: 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
9a30: 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
9a40: 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a  ler is cleared..
9a50: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
9a60: 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
9a70: 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
9a80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9a90: 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
9aa0: 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
9ab0: 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54   Queries.**.** T
9ac0: 68 69 73 20 6e 65 78 74 20 72 6f 75 74 69 6e 65  his next routine
9ad0: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63   is a convenienc
9ae0: 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  e wrapper around
9af0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
9b00: 5d 2e 0a 2a 2a 20 49 6e 73 74 65 61 64 20 6f 66  ]..** Instead of
9b10: 20 69 6e 76 6f 6b 69 6e 67 20 61 20 75 73 65 72   invoking a user
9b20: 2d 73 75 70 70 6c 69 65 64 20 63 61 6c 6c 62 61  -supplied callba
9b30: 63 6b 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20  ck for each row 
9b40: 6f 66 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  of the.** result
9b50: 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  , this routine r
9b60: 65 6d 65 6d 62 65 72 73 20 65 61 63 68 20 72 6f  emembers each ro
9b70: 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
9b80: 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74  in memory.** obt
9b90: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
9ba0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 74  te3_malloc()], t
9bb0: 68 65 6e 20 72 65 74 75 72 6e 73 20 61 6c 6c 20  hen returns all 
9bc0: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 61 66  of the result af
9bd0: 74 65 72 20 74 68 65 0a 2a 2a 20 71 75 65 72 79  ter the.** query
9be0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 2e 20 0a   has finished. .
9bf0: 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d  **.** As an exam
9c00: 70 6c 65 2c 20 73 75 70 70 6f 73 65 20 74 68 65  ple, suppose the
9c10: 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 77 68   query result wh
9c20: 65 72 65 20 74 68 69 73 20 74 61 62 6c 65 3a 0a  ere this table:.
9c30: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
9c40: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
9c50: 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
9c60: 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
9c70: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
9c80: 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
9c90: 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
9ca0: 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
9cb0: 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
9cc0: 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
9cd0: 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
9ce0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
9cf0: 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 61  .** If the 3rd a
9d00: 72 67 75 6d 65 6e 74 20 77 65 72 65 20 26 61 7a  rgument were &az
9d10: 52 65 73 75 6c 74 20 74 68 65 6e 20 61 66 74 65  Result then afte
9d20: 72 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72  r the function r
9d30: 65 74 75 72 6e 73 0a 2a 2a 20 61 7a 52 65 73 75  eturns.** azResu
9d40: 6c 74 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  lt will contain 
9d50: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 61  the following da
9d60: 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ta:.**.** <block
9d70: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
9d80: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
9d90: 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
9da0: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
9db0: 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
9dc0: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
9dd0: 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
9de0: 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
9df0: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
9e00: 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
9e10: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
9e20: 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
9e30: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
9e40: 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
9e50: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
9e60: 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
9e70: 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
9e80: 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
9e90: 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
9ea0: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
9eb0: 2a 2a 20 4e 6f 74 69 63 65 20 74 68 61 74 20 74  ** Notice that t
9ec0: 68 65 72 65 20 69 73 20 61 6e 20 65 78 74 72 61  here is an extra
9ed0: 20 72 6f 77 20 6f 66 20 64 61 74 61 20 63 6f 6e   row of data con
9ee0: 74 61 69 6e 69 6e 67 20 74 68 65 20 63 6f 6c 75  taining the colu
9ef0: 6d 6e 0a 2a 2a 20 68 65 61 64 65 72 73 2e 20 20  mn.** headers.  
9f00: 42 75 74 20 74 68 65 20 2a 6e 72 6f 77 20 72 65  But the *nrow re
9f10: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20 73 74  turn value is st
9f20: 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f 6c 75 6d 6e  ill 3.  *ncolumn
9f30: 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20 32 2e   is.** set to 2.
9f40: 20 20 49 6e 20 67 65 6e 65 72 61 6c 2c 20 74 68    In general, th
9f50: 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75  e number of valu
9f60: 65 73 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  es inserted into
9f70: 20 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 77 69 6c   azResult.** wil
9f80: 6c 20 62 65 20 28 28 2a 6e 72 6f 77 29 20 2b 20  l be ((*nrow) + 
9f90: 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e 29 2e 0a 2a  1)*(*ncolumn)..*
9fa0: 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63  *.** After the c
9fb0: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
9fc0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
9fd0: 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69  ng the result, i
9fe0: 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 61 73  t should .** pas
9ff0: 73 20 74 68 65 20 72 65 73 75 6c 74 20 64 61 74  s the result dat
a000: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  a pointer to sql
a010: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
a020: 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 0a 2a  ) in order to .*
a030: 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
a040: 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
a050: 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61 75 73  lloc-ed.  Becaus
a060: 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
a070: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
a080: 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 2c  lloc()] happens,
a090: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
a0a0: 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
a0b0: 72 79 20 74 6f 20 63 61 6c 6c 20 0a 2a 2a 20 5b  ry to call .** [
a0c0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
a0d0: 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 20  directly.  Only 
a0e0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
a0f0: 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
a100: 6f 20 72 65 6c 65 61 73 65 20 0a 2a 2a 20 74 68  o release .** th
a110: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
a120: 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
a130: 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76  .** The return v
a140: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75  alue of this rou
a150: 74 69 6e 65 20 69 73 20 74 68 65 20 73 61 6d 65  tine is the same
a160: 20 61 73 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65   as from [sqlite
a170: 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2f 0a 69 6e  3_exec()]..*/.in
a180: 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
a190: 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ble(.  sqlite3*,
a1a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
a1b0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
a1c0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
a1d0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 2f 2a  r *sql,       /*
a1e0: 20 53 51 4c 20 74 6f 20 62 65 20 65 78 65 63 75   SQL to be execu
a1f0: 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
a200: 2a 72 65 73 75 6c 74 70 2c 20 20 20 20 20 20 20  *resultp,       
a210: 2f 2a 20 52 65 73 75 6c 74 20 77 72 69 74 74 65  /* Result writte
a220: 6e 20 74 6f 20 61 20 63 68 61 72 20 2a 5b 5d 20  n to a char *[] 
a230: 20 74 68 61 74 20 74 68 69 73 20 70 6f 69 6e 74   that this point
a240: 73 20 74 6f 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e  s to */.  int *n
a250: 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 20  row,            
a260: 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
a270: 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
a280: 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
a290: 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  *ncolumn,       
a2a0: 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
a2b0: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
a2c0: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
a2d0: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
a2e0: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
a2f0: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
a300: 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
a310: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
a320: 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
a330: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a340: 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
a350: 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
a360: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
a370: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
a380: 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  rkalikes of the 
a390: 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
a3a0: 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
a3b0: 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
a3c0: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
a3d0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
a3e0: 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
a3f0: 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
a400: 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
a410: 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
a420: 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
a430: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
a440: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
a450: 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
a460: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
a470: 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
a480: 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
a490: 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
a4a0: 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72  free()].  Both r
a4b0: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
a4c0: 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
a4d0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
a4e0: 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
a4f0: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
a500: 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
a510: 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
a520: 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
a530: 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70  * In sqlite3_snp
a540: 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
a550: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
a560: 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
a570: 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
a580: 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
a590: 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
a5a0: 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
a5b0: 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
a5c0: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
a5d0: 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
a5e0: 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
a5f0: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
a600: 74 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  ter.  Note that 
a610: 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
a620: 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
a630: 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
a640: 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
a650: 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61  tf().  This is a
a660: 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
a670: 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
a680: 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
a690: 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
a6a0: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
a6b0: 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65  atibility.  Note
a6c0: 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
a6d0: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
a6e0: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
a6f0: 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
a700: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
a710: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
a720: 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
a730: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
a740: 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64  e buffer.  We ad
a750: 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
a760: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
a770: 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
a780: 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
a790: 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
a7a0: 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
a7b0: 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
a7c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
a7d0: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
a7e0: 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
a7f0: 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
a800: 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41  ibility..**.** A
a810: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
a820: 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
a830: 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
a840: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
a850: 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
a860: 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
a870: 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
a880: 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
a890: 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
a8a0: 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
a8b0: 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
a8c0: 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
a8d0: 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
a8e0: 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
a8f0: 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
a900: 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
a910: 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
a920: 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
a930: 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
a940: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
a950: 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
a960: 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
a970: 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
a980: 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
a990: 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
a9a0: 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
a9b0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
a9c0: 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
a9d0: 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d 61  ual printf forma
a9e0: 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
a9f0: 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
aa00: 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
aa10: 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
aa20: 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
aa30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
aa40: 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
aa50: 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
aa60: 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
aa70: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
aa80: 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
aa90: 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
aaa0: 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
aab0: 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
aac0: 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
aad0: 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
aae0: 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
aaf0: 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
ab00: 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
ab10: 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
ab20: 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
ab30: 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
ab40: 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
ab50: 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
ab60: 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
ab70: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f   For example, so
ab80: 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 72   some string var
ab90: 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74  iable contains t
aba0: 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
abb0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
abc0: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
abd0: 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
abe0: 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
abf0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
ac00: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
ac10: 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
ac20: 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
ac30: 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
ac40: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
ac50: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
ac60: 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
ac70: 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
ac80: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
ac90: 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
aca0: 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
acb0: 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
acc0: 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
acd0: 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
ace0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
acf0: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
ad00: 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
ad10: 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
ad20: 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
ad30: 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
ad40: 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
ad50: 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
ad60: 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
ad70: 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
ad80: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
ad90: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
ada0: 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
adb0: 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
adc0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
add0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
ade0: 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
adf0: 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
ae00: 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
ae10: 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
ae20: 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
ae30: 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
ae40: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
ae50: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
ae60: 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
ae70: 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
ae80: 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
ae90: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
aea0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
aeb0: 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
aec0: 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
aed0: 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
aee0: 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68  l rule you.** sh
aef0: 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73 65 20  ould always use 
af00: 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
af10: 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
af20: 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
af30: 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a  ng .** literal..
af40: 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74  **.** The %Q opt
af50: 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
af60: 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
af70: 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
af80: 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
af90: 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
afa0: 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
afb0: 4f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  Or if the parame
afc0: 74 65 72 20 69 6e 20 74 68 65 20 61 72 67 75 6d  ter in the argum
afd0: 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61  ent.** list is a
afe0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
aff0: 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
b000: 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
b010: 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a  ithout single.**
b020: 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
b030: 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
b040: 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  on.  So, for exa
b050: 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
b060: 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
b070: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
b080: 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
b090: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
b0a0: 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
b0b0: 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
b0c0: 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
b0d0: 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
b0e0: 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
b0f0: 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
b100: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
b110: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
b120: 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
b130: 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
b140: 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
b150: 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
b160: 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
b170: 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
b180: 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
b190: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
b1a0: 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
b1b0: 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
b1c0: 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
b1d0: 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
b1e0: 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
b1f0: 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
b200: 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
b210: 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
b220: 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
b230: 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
b240: 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
b250: 74 20 73 74 72 69 6e 67 2e 0a 2a 2f 0a 63 68 61  t string..*/.cha
b260: 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
b270: 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
b280: 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
b290: 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
b2a0: 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
b2b0: 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
b2c0: 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
b2d0: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
b2e0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
b2f0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
b300: 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
b310: 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
b320: 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
b330: 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
b340: 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
b350: 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
b360: 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
b370: 74 69 6f 6e 20 6e 65 65 64 73 2e 20 54 68 65 20  tion needs. The 
b380: 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e  default implemen
b390: 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
b3a0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b3b0: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65  on subsystem use
b3c0: 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20  s the malloc(), 
b3d0: 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64  realloc().** and
b3e0: 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64   free() provided
b3f0: 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64   by the standard
b400: 20 43 20 6c 69 62 72 61 72 79 2e 20 20 48 6f 77   C library.  How
b410: 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c  ever, if .** SQL
b420: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
b430: 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69  with the followi
b440: 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  ng C preprocesso
b450: 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62  r macro.**.** <b
b460: 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54  lockquote> SQLIT
b470: 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
b480: 4c 4f 43 41 54 49 4f 4e 20 3c 2f 62 6c 6f 63 6b  LOCATION </block
b490: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 74 68 65  quote>.**.** the
b4a0: 6e 20 6e 6f 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n no implementat
b4b0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
b4c0: 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
b4d0: 65 73 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 2e  es by.** SQLite.
b4e0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
b4f0: 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  n that links aga
b500: 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a  inst SQLite is.*
b510: 2a 20 65 78 70 65 63 74 65 64 20 74 6f 20 70 72  * expected to pr
b520: 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20 69 6d  ovide its own im
b530: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 49  plementation.  I
b540: 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
b550: 6e 0a 2a 2a 20 64 6f 65 73 20 70 72 6f 76 69 64  n.** does provid
b560: 65 20 69 74 73 20 6f 77 6e 20 69 6d 70 6c 65 6d  e its own implem
b570: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  entation for the
b580: 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 74 68 65  se routines, the
b590: 6e 0a 2a 2a 20 69 74 20 6d 75 73 74 20 61 6c 73  n.** it must als
b5a0: 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70  o provide an imp
b5b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
b5c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
b5d0: 72 79 5f 61 6c 61 72 6d 28 29 5d 2e 0a 2a 2a 0a  ry_alarm()]..**.
b5e0: 2a 2a 20 3c 62 3e 45 78 63 65 70 74 69 6f 6e 3a  ** <b>Exception:
b5f0: 3c 2f 62 3e 20 54 68 65 20 77 69 6e 64 6f 77 73  </b> The windows
b600: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
b610: 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
b620: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
b630: 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
b640: 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
b650: 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
b660: 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
b670: 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
b680: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
b690: 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
b6a0: 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
b6b0: 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
b6c0: 74 69 63 75 6c 61 72 20 77 69 6e 64 6f 77 73 0a  ticular windows.
b6d0: 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
b6e0: 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
b6f0: 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
b700: 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
b710: 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
b720: 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
b730: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
b740: 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
b750: 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
b760: 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a  LITE_NOMEM]..*/.
b770: 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
b780: 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
b790: 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
b7a0: 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
b7b0: 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
b7c0: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
b7d0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
b7e0: 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
b7f0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64  tics.**.** In ad
b800: 64 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 62 61  dition to the ba
b810: 73 69 63 20 74 68 72 65 65 20 61 6c 6c 6f 63 61  sic three alloca
b820: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a 2a  tion routines .*
b830: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
b840: 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
b850: 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
b860: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c  ite3_realloc()],
b870: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
b880: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
b890: 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74  tem included wit
b8a0: 68 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  h the SQLite.** 
b8b0: 73 6f 75 72 63 65 73 20 70 72 6f 76 69 64 65 73  sources provides
b8c0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
b8d0: 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 0a  shown below..**.
b8e0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 6f 66 20  ** The first of 
b8f0: 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
b900: 65 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  es returns the a
b910: 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20  mount of memory 
b920: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  .** currently ou
b930: 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
b940: 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
b950: 64 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a  d).  The second.
b960: 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c  ** returns the l
b970: 61 72 67 65 73 74 20 69 6e 73 74 61 6e 74 61 6e  argest instantan
b980: 65 6f 75 73 20 61 6d 6f 75 6e 74 20 6f 66 20 6f  eous amount of o
b990: 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 6d 65  utstanding.** me
b9a0: 6d 6f 72 79 2e 20 20 54 68 65 20 68 69 67 68 77  mory.  The highw
b9b0: 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
b9c0: 65 74 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  et if the argume
b9d0: 6e 74 20 69 73 0a 2a 2a 20 74 72 75 65 2e 20 20  nt is.** true.  
b9e0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
b9f0: 64 6f 65 73 20 6e 6f 74 20 75 73 65 20 65 69 74  does not use eit
ba00: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
ba10: 74 69 6e 65 73 0a 2a 2a 20 61 6e 64 20 73 6f 20  tines.** and so 
ba20: 74 68 65 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  they do not have
ba30: 20 74 6f 20 62 65 20 69 6d 70 6c 65 6d 65 6e 74   to be implement
ba40: 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
ba50: 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 53 51 4c 49  ation.** if SQLI
ba60: 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
ba70: 4c 4c 4f 43 41 54 49 4f 4e 20 69 73 20 64 65 66  LLOCATION is def
ba80: 69 6e 65 64 2e 20 20 54 68 65 73 65 20 72 6f 75  ined.  These rou
ba90: 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 72 6f  tines.** are pro
baa0: 76 69 64 65 64 20 62 79 20 74 68 65 20 64 65 66  vided by the def
bab0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 73 75 62 73  ault memory subs
bac0: 79 73 74 65 6d 20 66 6f 72 20 64 69 61 67 6e 6f  ystem for diagno
bad0: 73 74 69 63 0a 2a 2a 20 70 75 72 70 6f 73 65 73  stic.** purposes
bae0: 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
baf0: 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
bb00: 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
bb10: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
bb20: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
bb30: 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
bb40: 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
bb50: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
bb60: 6f 63 61 74 69 6f 6e 20 41 6c 61 72 6d 73 0a 2a  ocation Alarms.*
bb70: 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
bb80: 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 5d 20  3_memory_alarm] 
bb90: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20  routine is used 
bba0: 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 61  to register.** a
bbb0: 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 6d 65 6d   callback on mem
bbc0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
bbd0: 76 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  vents..**.** Thi
bbe0: 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
bbf0: 65 72 73 20 6f 72 20 63 6c 65 61 72 73 20 61 20  ers or clears a 
bc00: 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 66  callbacks that f
bc10: 69 72 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65  ires when.** the
bc20: 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
bc30: 79 20 61 6c 6c 6f 63 61 74 65 64 20 65 78 63 65  y allocated exce
bc40: 65 64 73 20 69 54 68 72 65 73 68 6f 6c 64 2e 20  eds iThreshold. 
bc50: 20 4f 6e 6c 79 0a 2a 2a 20 61 20 73 69 6e 67 6c   Only.** a singl
bc60: 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 62  e callback can b
bc70: 65 20 72 65 67 69 73 74 65 72 65 64 20 61 74 20  e registered at 
bc80: 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
bc90: 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
bca0: 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29  3_memory_alarm()
bcb0: 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  ] overwrites the
bcc0: 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 62 61   previous callba
bcd0: 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  ck..** The callb
bce0: 61 63 6b 20 69 73 20 64 69 73 61 62 6c 65 64 20  ack is disabled 
bcf0: 62 79 20 73 65 74 74 69 6e 67 20 78 43 61 6c 6c  by setting xCall
bd00: 62 61 63 6b 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  back to a NULL.*
bd10: 2a 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a  * pointer..** .*
bd20: 2a 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 73  * The parameters
bd30: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
bd40: 20 61 72 65 20 74 68 65 20 70 41 72 67 20 76 61   are the pArg va
bd50: 6c 75 65 2c 20 74 68 65 20 0a 2a 2a 20 61 6d 6f  lue, the .** amo
bd60: 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  unt of memory cu
bd70: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2c 20  rrently in use, 
bd80: 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  and the size of 
bd90: 74 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  the.** allocatio
bda0: 6e 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20  n that provoked 
bdb0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  the callback.  T
bdc0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c  he callback will
bdd0: 0a 2a 2a 20 70 72 65 73 75 6d 61 62 6c 79 20 69  .** presumably i
bde0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
bdf0: 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 20 75  ree()] to free u
be00: 70 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 2e 0a  p memory space..
be10: 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
be20: 6d 61 79 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  may invoke [sqli
be30: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
be40: 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
be50: 63 28 29 5d 0a 2a 2a 20 62 75 74 20 69 66 20 69  c()].** but if i
be60: 74 20 64 6f 65 73 2c 20 6e 6f 20 61 64 64 69 74  t does, no addit
be70: 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  ional callbacks 
be80: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
be90: 62 79 0a 2a 2a 20 74 68 65 20 72 65 63 75 72 73  by.** the recurs
bea0: 69 76 65 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a  ive calls..**.**
beb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   The [sqlite3_so
bec0: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d  ft_heap_limit()]
bed0: 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
bee0: 20 62 79 20 72 65 67 69 73 74 65 72 69 6e 67 0a   by registering.
bef0: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 61 72  ** a memory alar
bf00: 6d 20 61 74 20 74 68 65 20 73 6f 66 74 20 68 65  m at the soft he
bf10: 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 69 6e 76  ap limit and inv
bf20: 6f 6b 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  oking .** [sqlit
bf30: 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
bf40: 79 28 29 5d 20 69 6e 20 74 68 65 20 61 6c 61 72  y()] in the alar
bf50: 6d 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 70 70  m callback.  App
bf60: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 6f 67  lication.** prog
bf70: 72 61 6d 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  rams should not 
bf80: 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
bf90: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
bfa0: 72 79 5f 61 6c 61 72 6d 28 29 5d 0a 2a 2a 20 69  ry_alarm()].** i
bfb0: 6e 74 65 72 66 61 63 65 20 62 65 63 61 75 73 65  nterface because
bfc0: 20 64 6f 69 6e 67 20 73 6f 20 77 69 6c 6c 20 69   doing so will i
bfd0: 6e 74 65 72 66 65 72 65 20 77 69 74 68 20 74 68  nterfere with th
bfe0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f  e.** [sqlite3_so
bff0: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d  ft_heap_limit()]
c000: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 69 73 20 69   module.  This i
c010: 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 6f  nterface is expo
c020: 73 65 64 0a 2a 2a 20 6f 6e 6c 79 20 73 6f 20 74  sed.** only so t
c030: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
c040: 20 63 61 6e 20 70 72 6f 76 69 64 65 20 74 68 65   can provide the
c050: 69 72 20 6f 77 6e 0a 2a 2a 20 61 6c 74 65 72 6e  ir own.** altern
c060: 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ative implementa
c070: 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 53 51  tion when the SQ
c080: 4c 69 74 65 20 63 6f 72 65 20 69 73 0a 2a 2a 20  Lite core is.** 
c090: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 53 51  compiled with SQ
c0a0: 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
c0b0: 5f 41 4c 4c 4f 43 41 54 49 4f 4e 2e 0a 2a 2f 0a  _ALLOCATION..*/.
c0c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
c0d0: 72 79 5f 61 6c 61 72 6d 28 0a 20 20 76 6f 69 64  ry_alarm(.  void
c0e0: 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 76 6f 69  (*xCallback)(voi
c0f0: 64 20 2a 70 41 72 67 2c 20 73 71 6c 69 74 65 33  d *pArg, sqlite3
c100: 5f 69 6e 74 36 34 20 75 73 65 64 2c 20 69 6e 74  _int64 used, int
c110: 20 4e 29 2c 0a 20 20 76 6f 69 64 20 2a 70 41 72   N),.  void *pAr
c120: 67 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74  g,.  sqlite3_int
c130: 36 34 20 69 54 68 72 65 73 68 6f 6c 64 0a 29 3b  64 iThreshold.);
c140: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
c150: 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
c160: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
c170: 6c 6c 62 61 63 6b 73 0a 2a 2a 2a 0a 2a 2a 20 54  llbacks.***.** T
c180: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
c190: 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a  sters a authoriz
c1a0: 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
c1b0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
c1c0: 61 72 79 2e 20 20 0a 2a 2a 20 54 68 65 20 61 75  ary.  .** The au
c1d0: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
c1e0: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
c1f0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
c200: 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
c210: 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
c220: 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
c230: 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
c240: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
c250: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
c260: 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
c270: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
c280: 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76  e16_v2()].  At v
c290: 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
c2a0: 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
c2b0: 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
c2c0: 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
c2d0: 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
c2e0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
c2f0: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
c300: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
c310: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
c320: 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
c330: 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
c340: 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72  wed.  The author
c350: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
c360: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 53  ould.** return S
c370: 51 4c 49 54 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f  QLITE_OK to allo
c380: 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
c390: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
c3a0: 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
c3b0: 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
c3c0: 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
c3d0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
c3e0: 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
c3f0: 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
c400: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
c410: 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
c420: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
c430: 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
c440: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
c450: 20 0a 2a 2a 0a 2a 2a 20 44 65 70 65 6e 64 69 6e   .**.** Dependin
c460: 67 20 6f 6e 20 74 68 65 20 61 63 74 69 6f 6e 2c  g on the action,
c470: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   the [SQLITE_IGN
c480: 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  ORE] and [SQLITE
c490: 5f 44 45 4e 59 5d 20 72 65 74 75 72 6e 0a 2a 2a  _DENY] return.**
c4a0: 20 63 6f 64 65 73 20 6d 69 67 68 74 20 6d 65 61   codes might mea
c4b0: 6e 20 73 6f 6d 65 74 68 69 6e 67 20 64 69 66 66  n something diff
c4c0: 65 72 65 6e 74 20 6f 72 20 74 68 65 79 20 6d 69  erent or they mi
c4d0: 67 68 74 20 6d 65 61 6e 20 74 68 65 20 73 61 6d  ght mean the sam
c4e0: 65 0a 2a 2a 20 74 68 69 6e 67 2e 20 20 49 66 20  e.** thing.  If 
c4f0: 74 68 65 20 61 63 74 69 6f 6e 20 69 73 2c 20 66  the action is, f
c500: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 70  or example, to p
c510: 65 72 66 6f 72 6d 20 61 20 64 65 6c 65 74 65 20  erform a delete 
c520: 6f 70 65 72 74 69 6f 6e 2c 0a 2a 2a 20 74 68 65  opertion,.** the
c530: 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
c540: 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45  ] and [SQLITE_DE
c550: 4e 59 5d 20 62 6f 74 68 20 63 61 75 73 65 20 74  NY] both cause t
c560: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  he statement com
c570: 70 69 6c 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66  pilation.** to f
c580: 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
c590: 72 2e 20 20 42 75 74 20 69 66 20 74 68 65 20 61  r.  But if the a
c5a0: 63 74 69 6f 6e 20 69 73 20 74 6f 20 72 65 61 64  ction is to read
c5b0: 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75   a specific colu
c5c0: 6d 6e 0a 2a 2a 20 66 72 6f 6d 20 61 20 73 70 65  mn.** from a spe
c5d0: 63 69 66 69 63 20 74 61 62 6c 65 2c 20 74 68 65  cific table, the
c5e0: 6e 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  n [SQLITE_DENY] 
c5f0: 77 69 6c 6c 20 63 61 75 73 65 20 74 68 65 20 65  will cause the e
c600: 6e 74 69 72 65 0a 2a 2a 20 73 74 61 74 65 6d 65  ntire.** stateme
c610: 6e 74 20 74 6f 20 66 61 69 6c 20 62 75 74 20 5b  nt to fail but [
c620: 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 77  SQLITE_IGNORE] w
c630: 69 6c 6c 20 63 61 75 73 65 20 61 20 4e 55 4c 4c  ill cause a NULL
c640: 20 76 61 6c 75 65 20 74 6f 20 62 65 0a 2a 2a 20   value to be.** 
c650: 72 65 61 64 20 69 6e 73 74 65 61 64 20 6f 66 20  read instead of 
c660: 74 68 65 20 61 63 74 75 61 6c 20 63 6f 6c 75 6d  the actual colum
c670: 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  n value..**.** T
c680: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
c690: 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
c6a0: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
c6b0: 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
c6c0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
c6d0: 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
c6e0: 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
c6f0: 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  ) interface..** 
c700: 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
c710: 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
c720: 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
c730: 65 72 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  er .** [SQLITE_C
c740: 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
c750: 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
c760: 73 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  s the particular
c770: 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65   action.** to be
c780: 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
c790: 65 20 61 76 61 69 6c 61 62 6c 65 20 61 63 74 69  e available acti
c7a0: 6f 6e 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  on codes are.** 
c7b0: 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 64  [SQLITE_COPY | d
c7c0: 6f 63 75 6d 65 6e 74 65 64 20 73 65 70 61 72 61  ocumented separa
c7d0: 74 65 6c 79 5d 2e 20 20 54 68 65 20 74 68 69 72  tely].  The thir
c7e0: 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 0a  d through sixth.
c7f0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ** parameters to
c800: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
c810: 65 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  e strings that c
c820: 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
c830: 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
c840: 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
c850: 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
c860: 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
c870: 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
c880: 20 70 72 65 70 61 72 69 6e 67 20 53 51 4c 20 73   preparing SQL s
c890: 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
c8a0: 6e 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73  n untrusted.** s
c8b0: 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
c8c0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
c8d0: 61 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20  atements do not 
c8e0: 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
c8f0: 74 61 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20  ta.** that they 
c900: 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
c910: 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
c920: 74 68 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20  they do not try 
c930: 74 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61  to.** execute ma
c940: 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
c950: 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
c960: 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
c970: 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
c980: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
c990: 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
c9a0: 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
c9b0: 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
c9c0: 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
c9d0: 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
c9e0: 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
c9f0: 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
ca00: 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
ca10: 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
ca20: 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
ca30: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
ca40: 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
ca50: 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
ca60: 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
ca70: 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
ca80: 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
ca90: 20 62 65 69 6e 67 20 70 72 65 70 61 72 65 64 20   being prepared 
caa0: 74 68 61 74 20 64 69 73 61 6c 6c 6f 77 73 20 65  that disallows e
cab0: 76 65 72 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63  verything.** exc
cac0: 65 70 74 20 53 45 4c 45 43 54 20 73 74 61 74 65  ept SELECT state
cad0: 6d 65 6e 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f  ments.  .**.** O
cae0: 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
caf0: 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
cb00: 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
cb10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
cb20: 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
cb30: 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
cb40: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
cb50: 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
cb60: 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
cb70: 6c 6c 2e 20 20 41 20 4e 55 4c 4c 20 61 75 74 68  ll.  A NULL auth
cb80: 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61  orizer means tha
cb90: 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69  t no authorizati
cba0: 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  on.** callback i
cbb0: 73 20 69 6e 76 6f 6b 65 64 2e 20 20 54 68 65 20  s invoked.  The 
cbc0: 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a  default authoriz
cbd0: 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  er is NULL..**.*
cbe0: 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
cbf0: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
cc00: 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
cc10: 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b  nly during .** [
cc20: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
cc30: 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
cc40: 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
cc50: 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
cc60: 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
cc70: 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
cc80: 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
cc90: 74 65 70 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  tep()]..*/.int s
cca0: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
ccb0: 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
ccc0: 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
ccd0: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
cce0: 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
ccf0: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
cd00: 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
cd10: 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
cd20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
cd30: 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
cd40: 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
cd50: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
cd60: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
cd70: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
cd80: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
cd90: 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
cda0: 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
cdb0: 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
cdc0: 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
cdd0: 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
cde0: 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
cdf0: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
ce00: 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
ce10: 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
ce20: 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
ce30: 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
ce40: 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
ce50: 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
ce60: 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
ce70: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
ce80: 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
ce90: 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
cea0: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
ceb0: 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
cec0: 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
ced0: 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
cee0: 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
cef0: 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
cf00: 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
cf10: 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
cf20: 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
cf30: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
cf40: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
cf50: 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
cf60: 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
cf70: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
cf80: 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
cf90: 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
cfa0: 72 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  r certain SQL st
cfb0: 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
cfc0: 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
cfd0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
cfe0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
cff0: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
d000: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
d010: 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
d020: 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
d030: 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
d040: 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
d050: 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
d060: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
d070: 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
d080: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
d090: 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
d0a0: 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
d0b0: 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
d0c0: 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75   is to be .** au
d0d0: 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
d0e0: 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
d0f0: 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
d100: 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62  horization callb
d110: 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
d120: 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
d130: 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
d140: 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
d150: 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
d160: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
d170: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
d180: 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
d190: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
d1a0: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
d1b0: 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
d1c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
d1d0: 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a  main", "temp", .
d1e0: 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
d1f0: 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68  icable.  The 6th
d200: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
d210: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
d220: 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
d230: 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
d240: 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
d250: 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
d260: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
d270: 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
d280: 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
d290: 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
d2a0: 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
d2b0: 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76  from .** top-lev
d2c0: 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
d2d0: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
d2e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d2f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
d300: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
d310: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
d320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
d330: 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
d340: 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
d350: 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
d360: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
d370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
d380: 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
d390: 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
d3a0: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
d3b0: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
d3c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
d3d0: 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
d3e0: 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
d3f0: 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
d400: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
d410: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
d420: 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
d430: 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
d440: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
d450: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
d460: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
d470: 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
d480: 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
d490: 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
d4a0: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
d4b0: 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
d4c0: 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
d4d0: 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
d4e0: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
d4f0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
d500: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
d510: 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
d520: 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
d530: 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
d540: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
d550: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
d560: 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
d570: 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
d580: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
d590: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
d5a0: 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
d5b0: 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
d5c0: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
d5d0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
d5e0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
d5f0: 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
d600: 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
d610: 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
d620: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
d630: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
d640: 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
d650: 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
d660: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
d670: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
d680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d690: 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
d6a0: 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
d6b0: 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
d6c0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
d6d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d6e0: 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
d6f0: 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
d700: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
d710: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
d720: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d730: 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
d740: 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
d750: 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
d760: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
d770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d780: 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
d790: 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
d7a0: 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
d7b0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
d7c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
d7d0: 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
d7e0: 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
d7f0: 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
d800: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
d810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
d820: 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
d830: 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
d840: 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
d850: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
d860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
d870: 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
d880: 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
d890: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
d8a0: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
d8b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
d8c0: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
d8d0: 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
d8e0: 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
d8f0: 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
d900: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
d910: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d920: 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
d930: 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
d940: 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
d950: 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
d960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d970: 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
d980: 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
d990: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
d9a0: 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
d9b0: 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
d9c0: 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
d9d0: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
d9e0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
d9f0: 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
da00: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
da10: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
da20: 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
da30: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
da40: 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
da50: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
da60: 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
da70: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
da80: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
da90: 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
daa0: 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
dab0: 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
dac0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
dad0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
dae0: 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
daf0: 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
db00: 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
db10: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
db20: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
db30: 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
db40: 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
db50: 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
db60: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
db70: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
db80: 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
db90: 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
dba0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
dbb0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
dbc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dbd0: 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
dbe0: 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
dbf0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
dc00: 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
dc10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dc20: 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
dc30: 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
dc40: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
dc50: 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
dc60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc70: 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
dc80: 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e       31   /* Fun
dc90: 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c  ction Name   NUL
dca0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
dcb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
dcc0: 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
dcd0: 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
dce0: 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
dcf0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
dd00: 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
dd10: 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
dd20: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
dd30: 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
dd40: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
dd50: 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
dd60: 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
dd70: 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
dd80: 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
dd90: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
dda0: 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
ddb0: 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
ddc0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
ddd0: 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
dde0: 0a 2a 2a 20 61 74 20 74 68 65 20 66 69 72 73 74  .** at the first
ddf0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
de00: 5d 20 66 6f 72 20 74 68 65 20 65 76 61 6c 75 61  ] for the evalua
de10: 74 69 6f 6e 20 6f 66 20 61 6e 20 53 51 4c 20 73  tion of an SQL s
de20: 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  tatement..** The
de30: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
de40: 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
de50: 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
de60: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
de70: 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
de80: 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 20  tement finishes 
de90: 61 6e 64 20 69 6e 63 6c 75 64 65 73 0a 2a 2a 20  and includes.** 
dea0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6f 6e 20 68  information on h
deb0: 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
dec0: 74 65 6d 65 6e 74 20 72 61 6e 2e 0a 2a 2a 0a 2a  tement ran..**.*
ded0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
dee0: 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73 20 63  ofile() API is c
def0: 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
df00: 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
df10: 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65   and.** is subje
df20: 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f  ct to change..*/
df30: 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
df40: 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
df50: 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
df60: 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
df70: 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
df80: 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
df90: 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
dfa0: 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
dfb0: 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
dfc0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
dfd0: 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
dfe0: 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
dff0: 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
e000: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
e010: 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61  ine configures a
e020: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
e030: 6f 6e 20 2d 20 74 68 65 20 70 72 6f 67 72 65 73  on - the progres
e040: 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61  s callback - tha
e050: 74 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20  t.** is invoked 
e060: 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
e070: 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
e080: 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
e090: 65 33 5f 65 78 65 63 28 29 5d 2c 0a 2a 2a 20 5b  e3_exec()],.** [
e0a0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
e0b0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
e0c0: 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65  _table()].  An e
e0d0: 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
e0e0: 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63  his .** interfac
e0f0: 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
e100: 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
e110: 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
e120: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
e130: 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
e140: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
e150: 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c   every N virtual
e160: 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73   machine opcodes
e170: 2c 0a 2a 2a 20 77 68 65 72 65 20 4e 20 69 73 20  ,.** where N is 
e180: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
e190: 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ent to this func
e1a0: 74 69 6f 6e 2e 20 54 68 65 20 70 72 6f 67 72 65  tion. The progre
e1b0: 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  ss callback.** i
e1c0: 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66  tself is identif
e1d0: 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64  ied by the third
e1e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
e1f0: 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  s function. The 
e200: 66 6f 75 72 74 68 0a 2a 2a 20 61 72 67 75 6d 65  fourth.** argume
e210: 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  nt to this funct
e220: 69 6f 6e 20 69 73 20 61 20 76 6f 69 64 20 70 6f  ion is a void po
e230: 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  inter passed to 
e240: 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
e250: 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
e260: 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74 20 69  n each time it i
e270: 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
e280: 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   If a call to [s
e290: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
e2a0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
e2b0: 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 67 65  , or [sqlite3_ge
e2c0: 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 72 65  t_table()].** re
e2d0: 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74  sults in fewer t
e2e0: 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 20 62 65  han N opcodes be
e2f0: 69 6e 67 20 65 78 65 63 75 74 65 64 2c 20 74 68  ing executed, th
e300: 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  en the progress 
e310: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
e320: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a  never invoked..*
e330: 2a 20 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  * .** Only a sin
e340: 67 6c 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  gle progress cal
e350: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
e360: 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
e370: 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 6f 70 65   for each.** ope
e380: 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
e390: 63 74 69 6f 6e 2e 20 20 45 76 65 72 79 20 63 61  ction.  Every ca
e3a0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  ll to sqlite3_pr
e3b0: 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
e3c0: 0a 2a 2a 20 6f 76 65 72 77 72 69 74 65 73 20 74  .** overwrites t
e3d0: 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 74 68  he results of th
e3e0: 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  e previous call.
e3f0: 0a 2a 2a 20 54 6f 20 72 65 6d 6f 76 65 20 74 68  .** To remove th
e400: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
e410: 61 63 6b 20 61 6c 74 6f 67 65 74 68 65 72 2c 20  ack altogether, 
e420: 70 61 73 73 20 4e 55 4c 4c 20 61 73 20 74 68 65  pass NULL as the
e430: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
e440: 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  nt to this funct
e450: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
e460: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
e470: 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65  ack returns a re
e480: 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20  sult other than 
e490: 30 2c 20 74 68 65 6e 20 74 68 65 20 63 75 72 72  0, then the curr
e4a0: 65 6e 74 20 0a 2a 2a 20 71 75 65 72 79 20 69 73  ent .** query is
e4b0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 74 65 72   immediately ter
e4c0: 6d 69 6e 61 74 65 64 20 61 6e 64 20 61 6e 79 20  minated and any 
e4d0: 64 61 74 61 62 61 73 65 20 63 68 61 6e 67 65 73  database changes
e4e0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
e4f0: 20 54 68 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   The containing 
e500: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
e510: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
e520: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
e530: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
e540: 63 61 6c 6c 20 72 65 74 75 72 6e 73 20 53 51 4c  call returns SQL
e550: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 2e 20 20  ITE_INTERRUPT.  
e560: 20 54 68 69 73 20 66 65 61 74 75 72 65 0a 2a 2a   This feature.**
e570: 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 66 6f   can be used, fo
e580: 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 69 6d  r example, to im
e590: 70 6c 65 6d 65 6e 74 20 74 68 65 20 22 43 61 6e  plement the "Can
e5a0: 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
e5b0: 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 64 69 61  .** progress dia
e5c0: 6c 6f 67 20 62 6f 78 20 69 6e 20 61 20 47 55 49  log box in a GUI
e5d0: 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
e5e0: 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
e5f0: 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
e600: 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
e610: 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
e620: 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
e630: 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
e640: 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
e650: 2a 20 4f 70 65 6e 20 74 68 65 20 73 71 6c 69 74  * Open the sqlit
e660: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
e670: 22 66 69 6c 65 6e 61 6d 65 22 2e 20 20 54 68 65  "filename".  The
e680: 20 22 66 69 6c 65 6e 61 6d 65 22 20 69 73 20 55   "filename" is U
e690: 54 46 2d 38 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  TF-8.** encoded 
e6a0: 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
e6b0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
e6c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64  3_open_v2()] and
e6d0: 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 0a   UTF-16 encoded.
e6e0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
e6f0: 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
e700: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
e710: 29 5d 2e 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  )]..** An [sqlit
e720: 65 33 2a 5d 20 68 61 6e 64 6c 65 20 69 73 20 72  e3*] handle is r
e730: 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
e740: 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20 61 6e 20  , even.** if an 
e750: 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 49 66  error occurs. If
e760: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
e770: 20 6f 70 65 6e 65 64 20 28 6f 72 20 63 72 65 61   opened (or crea
e780: 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
e790: 79 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49  y,.** then [SQLI
e7a0: 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
e7b0: 65 64 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e  ed. Otherwise an
e7c0: 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
e7d0: 65 74 75 72 6e 65 64 2e 20 54 68 65 0a 2a 2a 20  eturned. The.** 
e7e0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
e7f0: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
e800: 72 72 6d 73 67 31 36 28 29 5d 20 20 72 6f 75 74  rrmsg16()]  rout
e810: 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
e820: 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
e830: 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
e840: 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
e850: 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a   the error..**.*
e860: 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e  * The default en
e870: 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
e880: 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
e890: 55 54 46 2d 38 20 69 66 0a 2a 2a 20 5b 73 71 6c  UTF-8 if.** [sql
e8a0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
e8b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
e8c0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  ()] is called an
e8d0: 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 66 20 5b  d.** UTF-16 if [
e8e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
e8f0: 5d 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ] is used..**.**
e900: 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
e910: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
e920: 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
e930: 64 2c 20 72 65 73 6f 75 72 63 65 73 20 61 73 73  d, resources ass
e940: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
e950: 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68  the [sqlite3*] h
e960: 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
e970: 72 65 6c 65 61 73 65 64 20 62 79 20 70 61 73 73  released by pass
e980: 69 6e 67 20 69 74 20 74 6f 0a 2a 2a 20 5b 73 71  ing it to.** [sq
e990: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
e9a0: 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
e9b0: 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
e9c0: 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
e9d0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
e9e0: 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
e9f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
ea00: 5d 20 65 78 63 65 70 74 20 74 68 61 74 0a 2a 2a  ] except that.**
ea10: 20 70 72 6f 76 69 64 65 73 20 74 77 6f 20 61 64   provides two ad
ea20: 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
ea30: 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
ea40: 61 6c 20 63 6f 6e 74 72 6f 6c 20 6f 76 65 72 20  al control over 
ea50: 74 68 65 0a 2a 2a 20 6e 65 77 20 64 61 74 61 62  the.** new datab
ea60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
ea70: 20 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   The flags param
ea80: 65 74 65 72 20 63 61 6e 20 62 65 20 6f 6e 65 20  eter can be one 
ea90: 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  of:.**.** <ol>.*
eaa0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
eab0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a  OPEN_READONLY].*
eac0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ead0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a  OPEN_READWRITE].
eae0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
eaf0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
eb00: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
eb10: 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e  CREATE].** </ol>
eb20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
eb30: 20 76 61 6c 75 65 20 6f 70 65 6e 73 20 74 68 65   value opens the
eb40: 20 64 61 74 61 62 61 73 65 20 72 65 61 64 2d 6f   database read-o
eb50: 6e 6c 79 2e 20 20 49 66 20 74 68 65 20 64 61 74  nly.  If the dat
eb60: 61 62 61 73 65 20 64 6f 65 73 0a 2a 2a 20 6e 6f  abase does.** no
eb70: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69  t previously exi
eb80: 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
eb90: 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 73  returned.  The s
eba0: 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65  econd option ope
ebb0: 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  ns.** the databa
ebc0: 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
ebd0: 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
ebe0: 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
ebf0: 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69 66  ng only if.** if
ec00: 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
ec10: 74 65 20 70 72 6f 74 65 63 74 65 64 2e 20 20 49  te protected.  I
ec20: 6e 20 65 69 74 68 65 72 20 63 61 73 65 20 74 68  n either case th
ec30: 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
ec40: 61 6c 72 65 61 64 79 0a 2a 2a 20 65 78 69 73 74  already.** exist
ec50: 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 69 73 20   or an error is 
ec60: 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 74  returned.  The t
ec70: 68 69 72 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e  hird option open
ec80: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
ec90: 2a 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  * for reading an
eca0: 64 20 77 72 69 74 69 6e 67 20 61 6e 64 20 63 72  d writing and cr
ecb0: 65 61 74 65 73 20 69 74 20 69 66 20 69 74 20 64  eates it if it d
ecc0: 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
ecd0: 65 78 69 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68  exist..** The th
ece0: 69 72 64 20 6f 70 74 69 6f 6e 73 20 69 73 20 62  ird options is b
ecf0: 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
ed00: 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 20  always used for 
ed10: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ed20: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
ed30: 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _open16()]..**.*
ed40: 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  * If the filenam
ed50: 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 20  e is ":memory:" 
ed60: 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  or an empty stri
ed70: 6e 67 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76  ng, then an priv
ed80: 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f 72 79  ate.** in-memory
ed90: 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65   database is cre
eda0: 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
edb0: 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69  nection.  This i
edc0: 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61 74 61  n-memory.** data
edd0: 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
ede0: 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
edf0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
ee00: 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
ee10: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  .** version of S
ee20: 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61 6b 65  QLite might make
ee30: 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
ee40: 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
ee50: 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62 65 67  ames.** that beg
ee60: 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
ee70: 63 68 61 72 61 63 74 65 72 2e 20 20 49 74 20 69  character.  It i
ee80: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
ee90: 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20 64 61  at .** when a da
eea0: 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
eeb0: 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  really does begi
eec0: 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20 74 68  n with.** ":" th
eed0: 61 74 20 79 6f 75 20 70 72 65 66 69 78 20 74 68  at you prefix th
eee0: 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
eef0: 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b 65 20  a pathname like 
ef00: 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f 69 64  "./" to.** avoid
ef10: 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
ef20: 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
ef30: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
ef40: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
ef50: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
ef60: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
ef70: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
ef80: 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
ef90: 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74  g system .** int
efa0: 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
efb0: 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
efc0: 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
efd0: 73 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66  se.  If the.** f
efe0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
eff0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
f000: 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
f010: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
f020: 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 75 73  .** object is us
f030: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
f040: 65 20 74 6f 20 77 69 6e 64 6f 77 73 20 75 73 65  e to windows use
f050: 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
f060: 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
f070: 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
f080: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69  ment.** of [sqli
f090: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  te3_open()] and 
f0a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
f0b0: 28 29 5d 20 6d 75 73 74 20 62 65 20 55 54 46 2d  ()] must be UTF-
f0c0: 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
f0d0: 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
f0e0: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
f0f0: 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
f100: 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
f110: 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
f120: 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
f130: 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
f140: 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
f150: 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  them into.** [sq
f160: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
f170: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
f180: 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2()]..*/.int sql
f190: 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
f1a0: 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
f1b0: 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
f1c0: 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
f1d0: 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
f1e0: 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
f1f0: 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
f200: 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
f210: 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
f220: 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
f230: 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
f240: 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
f250: 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
f260: 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
f270: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
f280: 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
f290: 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
f2a0: 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
f2b0: 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
f2c0: 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
f2d0: 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
f2e0: 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
f2f0: 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
f300: 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
f310: 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
f320: 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
f330: 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
f340: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
f350: 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
f360: 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
f370: 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
f380: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
f390: 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
f3a0: 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 54 68  essages.**.** Th
f3b0: 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
f3c0: 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
f3d0: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
f3e0: 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  c.** [SQLITE_OK 
f3f0: 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f  | result code] o
f400: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
f410: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
f420: 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20  result code].** 
f430: 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
f440: 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
f450: 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
f460: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
f470: 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c   [sqlite3] handl
f480: 65 20 27 64 62 27 2e 20 20 49 66 20 61 20 70 72  e 'db'.  If a pr
f490: 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
f4a0: 6c 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d  led but the.** m
f4b0: 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
f4c0: 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
f4d0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
f4e0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72  from sqlite3_err
f4f0: 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64  code().** is und
f500: 65 66 69 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54  efined. .**.** T
f510: 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
f520: 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
f530: 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
f540: 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 61 75  n English-langau
f550: 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
f560: 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
f570: 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
f580: 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73  TF8 or UTF16 res
f590: 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65  pectively..** Me
f5a0: 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
f5b0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
f5c0: 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
f5d0: 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 20 54 68   internally.  Th
f5e0: 65 20 0a 2a 2a 20 73 74 72 69 6e 67 20 6d 61 79  e .** string may
f5f0: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
f600: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
f610: 79 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  y subsequent cal
f620: 6c 73 20 74 6f 20 53 51 4c 69 74 65 0a 2a 2a 20  ls to SQLite.** 
f630: 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
f640: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 73  ons..**.** Calls
f650: 20 74 6f 20 6d 61 6e 79 20 73 71 6c 69 74 65 33   to many sqlite3
f660: 5f 2a 20 66 75 6e 63 74 69 6f 6e 73 20 73 65 74  _* functions set
f670: 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
f680: 61 6e 64 20 73 74 72 69 6e 67 20 72 65 74 75 72  and string retur
f690: 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
f6a0: 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
f6b0: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
f6c0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
f6d0: 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 28  errmsg16()].** (
f6e0: 6f 76 65 72 77 72 69 74 69 6e 67 20 74 68 65 20  overwriting the 
f6f0: 70 72 65 76 69 6f 75 73 20 76 61 6c 75 65 73 29  previous values)
f700: 2e 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c  . Note that call
f710: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
f720: 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71  rcode()],.** [sq
f730: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
f740: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
f750: 72 6d 73 67 31 36 28 29 5d 20 74 68 65 6d 73 65  rmsg16()] themse
f760: 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 66 66 65  lves do not affe
f770: 63 74 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  ct the.** result
f780: 73 20 6f 66 20 66 75 74 75 72 65 20 69 6e 76 6f  s of future invo
f790: 63 61 74 69 6f 6e 73 2e 20 20 43 61 6c 6c 73 20  cations.  Calls 
f7a0: 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  to API routines 
f7b0: 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75  that do not retu
f7c0: 72 6e 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63  rn.** an error c
f7d0: 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73  ode (example: [s
f7e0: 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
f7f0: 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20  t()]) do not.** 
f800: 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72  change the error
f810: 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62   code returned b
f820: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20  y this routine. 
f830: 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74   Interfaces that
f840: 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 61 73 73 6f   are.** not asso
f850: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70  ciated with a sp
f860: 65 63 69 66 69 63 20 64 61 74 61 62 61 73 65 20  ecific database 
f870: 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 65 78 61 6d  connection (exam
f880: 70 6c 65 73 3a 0a 2a 2a 20 5b 73 71 6c 69 74 65  ples:.** [sqlite
f890: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20  3_mprintf()] or 
f8a0: 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
f8b0: 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 20  shared_cache()] 
f8c0: 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a  do not change.**
f8d0: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
f8e0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69  .  .**.** Assumi
f8f0: 6e 67 20 6e 6f 20 6f 74 68 65 72 20 69 6e 74 65  ng no other inte
f900: 72 76 65 6e 69 6e 67 20 73 71 6c 69 74 65 33 5f  rvening sqlite3_
f910: 2a 20 41 50 49 20 63 61 6c 6c 73 20 61 72 65 20  * API calls are 
f920: 6d 61 64 65 2c 20 74 68 65 20 65 72 72 6f 72 0a  made, the error.
f930: 2a 2a 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64  ** code returned
f940: 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
f950: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
f960: 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 72  with the same er
f970: 72 6f 72 20 61 73 0a 2a 2a 20 74 68 65 20 73 74  ror as.** the st
f980: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
f990: 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  y [sqlite3_errms
f9a0: 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  g()] and [sqlite
f9b0: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
f9c0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
f9d0: 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
f9e0: 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
f9f0: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
fa00: 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
fa10: 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
fa20: 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
fa30: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fa40: 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
fa50: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 49 6e   Object.**.** In
fa60: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
fa70: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 20  bject represent 
fa80: 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
fa90: 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a 20  ments.  This.** 
faa0: 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
fab0: 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
fac0: 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
fad0: 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20  a .** "compiled 
fae0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
faf0: 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
fb00: 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a  tatement"..** .*
fb10: 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
fb20: 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
fb30: 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
fb40: 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
fb50: 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
fb60: 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
fb70: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
fb80: 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
fb90: 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
fba0: 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
fbb0: 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
fbc0: 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
fbd0: 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  rs using.**     
fbe0: 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
fbf0: 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
fc00: 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d  nd_* interfaces]
fc10: 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
fc20: 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
fc30: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
fc40: 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
fc50: 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
fc60: 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
fc70: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
fc80: 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
fc90: 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
fca0: 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
fcb0: 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
fcc0: 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
fcd0: 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
fce0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
fcf0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
fd00: 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
fd10: 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
fd20: 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
fd30: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
fd40: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
fd50: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
fd60: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
fd70: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
fd80: 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
fd90: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
fda0: 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
fdb0: 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  tement.**.** To 
fdc0: 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
fdd0: 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
fde0: 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
fdf0: 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
fe00: 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
fe10: 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
fe20: 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20  outines. .**.** 
fe30: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
fe40: 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b 73  nt "db" is an [s
fe50: 71 6c 69 74 65 33 20 7c 20 53 51 4c 69 74 65 20  qlite3 | SQLite 
fe60: 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d  database handle]
fe70: 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72   .** obtained fr
fe80: 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  om a prior call 
fe90: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
fea0: 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
feb0: 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 54 68  open16()]..** Th
fec0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
fed0: 74 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20  t "zSql" is the 
fee0: 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
fef0: 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
ff00: 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
ff10: 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
ff20: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
ff30: 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
ff40: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
ff50: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
ff60: 65 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c  es UTF-8 and sql
ff70: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
ff80: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
ff90: 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
ffa0: 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
ffb0: 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
ffc0: 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a 2a  gument is less.*
ffd0: 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  * than zero, the
ffe0: 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
fff0: 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
10000 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
10010 20 49 66 0a 2a 2a 20 6e 42 79 74 65 20 69 73 20   If.** nByte is 
10020 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
10030 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
10040 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 0a  imum number of .
10050 2a 2a 20 62 79 74 65 73 20 72 65 61 64 20 66 72  ** bytes read fr
10060 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e  om zSql.  When n
10070 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
10080 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
10090 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
100a0 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
100b0 74 20 27 5c 30 30 30 27 20 63 68 61 72 61 63 74  t '\000' charact
100c0 65 72 20 6f 72 20 0a 2a 2a 20 75 6e 74 69 6c 20  er or .** until 
100d0 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
100e0 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
100f0 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
10100 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
10110 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
10120 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
10130 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
10140 69 72 73 74 0a 2a 2a 20 53 51 4c 20 73 74 61 74  irst.** SQL stat
10150 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
10160 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
10170 79 20 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66  y compiles the f
10180 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 0a 2a  irst statement.*
10190 2a 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  * in zSql, so *p
101a0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
101b0 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72  inting to what r
101c0 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
101d0 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74  d..**.** *ppStmt
101e0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
101f0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
10200 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
10210 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  t | SQL statemen
10220 74 20 73 74 72 75 63 74 75 72 65 5d 20 74 68 61  t structure] tha
10230 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
10240 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
10250 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72  te3_step()].  Or
10260 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
10270 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 6d  error, *ppStmt m
10280 61 79 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f 20  ay be.** set to 
10290 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e  NULL.  If the in
102a0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
102b0 65 64 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ed no SQL (if th
102c0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 64 0a 2a  e input is and.*
102d0 2a 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  * empty string o
102e0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
102f0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
10300 20 74 6f 20 4e 55 4c 4c 2e 20 20 54 68 65 20 63   to NULL.  The c
10310 61 6c 6c 69 6e 67 0a 2a 2a 20 70 72 6f 63 65 64  alling.** proced
10320 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
10330 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
10340 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  the compiled SQL
10350 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73   statement.** us
10360 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
10370 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
10380 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
10390 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ith it..**.** On
103a0 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
103b0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
103c0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
103d0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
103e0 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d  OR | error code]
103f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
10400 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10410 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
10420 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
10430 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
10440 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
10450 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
10460 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
10470 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
10480 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
10490 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
104a0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
104b0 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
104c0 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
104d0 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  ** In the "v2" i
104e0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
104f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
10500 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
10510 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
10520 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
10530 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
10540 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69  y of the .** ori
10550 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
10560 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
10570 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
10580 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
10590 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72   behave a differ
105a0 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79  ently in two way
105b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
105c0 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20   <li>.** If the 
105d0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
105e0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
105f0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
10600 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
10610 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
10620 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
10630 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
10640 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
10650 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
10660 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
10670 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
10680 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63  gain.  If the sc
10690 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64  hema has changed
106a0 20 69 6e 20 61 20 77 61 79 0a 2a 2a 20 74 68 61   in a way.** tha
106b0 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74  t makes the stat
106c0 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20  ement no longer 
106d0 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f  valid, [sqlite3_
106e0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69  step()] will sti
106f0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
10700 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42  LITE_SCHEMA].  B
10710 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65  ut unlike the le
10720 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b  gacy behavior, [
10730 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69  SQLITE_SCHEMA] i
10740 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c  s.** now a fatal
10750 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67   error.  Calling
10760 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
10770 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69  e_v2()] again wi
10780 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a  ll not make the.
10790 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79  ** error go away
107a0 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71  .  Note: use [sq
107b0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
107c0 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74  to find the text
107d0 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 0a   of the parsing.
107e0 2a 2a 20 65 72 72 6f 72 20 74 68 61 74 20 72 65  ** error that re
107f0 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c  sults in an [SQL
10800 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75  ITE_SCHEMA] retu
10810 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  rn..** </li>.**.
10820 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20  ** <li>.** When 
10830 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
10840 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
10850 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
10860 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
10870 61 69 6c 65 64 20 0a 2a 2a 20 5b 53 51 4c 49 54  ailed .** [SQLIT
10880 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74  E_ERROR | result
10890 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 53   codes] or.** [S
108a0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
108b0 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
108c0 6c 74 20 63 6f 64 65 73 5d 20 73 75 63 68 20 61  lt codes] such a
108d0 73 20 64 69 72 65 63 74 6c 79 2e 0a 2a 2a 20 54  s directly..** T
108e0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
108f0 6f 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c  or was that [sql
10900 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
10910 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
10920 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c   generic.** [SQL
10930 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
10940 74 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77  t code and you w
10950 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
10960 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
10970 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
10980 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72  eset()] in order
10990 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
109a0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
109b0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a   the problem..**
109c0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
109d0 72 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65  repare interface
109e0 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
109f0 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
10a00 20 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74   error is.** ret
10a10 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
10a20 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  y..** </li>.** <
10a30 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
10a40 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
10a50 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
10a60 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
10a70 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
10a80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
10a90 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
10aa0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
10ab0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
10ac0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
10ad0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
10ae0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
10af0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
10b00 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
10b10 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
10b20 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
10b30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
10b40 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
10b50 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
10b60 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
10b70 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
10b80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
10b90 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
10ba0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
10bb0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
10bc0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
10bd0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
10be0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
10bf0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
10c00 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
10c10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
10c20 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
10c30 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
10c40 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
10c50 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
10c60 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
10c70 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
10c80 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
10c90 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
10ca0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
10cb0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
10cc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
10cd0 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
10ce0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
10cf0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
10d00 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
10d10 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
10d20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
10d30 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
10d40 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
10d50 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
10d60 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
10d70 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
10d80 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
10d90 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
10da0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
10db0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
10dc0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
10dd0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
10de0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
10df0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
10e00 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
10e10 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
10e20 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
10e30 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
10e40 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
10e50 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
10e60 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
10e70 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
10e80 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
10e90 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
10ea0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
10eb0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
10ec0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
10ed0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
10ee0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
10ef0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
10f00 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
10f10 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
10f20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
10f30 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
10f40 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
10f50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10f60 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79    Dynamically Ty
10f70 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
10f80 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
10f90 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
10fa0 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  g for the values
10fb0 20 69 74 20 73 74 6f 72 65 73 2e 20 20 56 61 6c   it stores.  Val
10fc0 75 65 73 20 63 61 6e 20 0a 2a 2a 20 62 65 20 69  ues can .** be i
10fd0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
10fe0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
10ff0 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
11000 6f 72 20 4e 55 4c 4c 2e 20 20 57 68 65 6e 0a 2a  or NULL.  When.*
11010 2a 20 70 61 73 73 69 6e 67 20 61 72 6f 75 6e 64  * passing around
11020 20 76 61 6c 75 65 73 20 69 6e 74 65 72 6e 61 6c   values internal
11030 6c 79 2c 20 65 61 63 68 20 76 61 6c 75 65 20 69  ly, each value i
11040 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
11050 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  .** an instance 
11060 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
11070 61 6c 75 65 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  alue object..*/.
11080 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
11090 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
110a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
110b0 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  F:  SQL Function
110c0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
110d0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
110e0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
110f0 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
11100 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
11110 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
11120 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
11130 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 75 63  A pointer to suc
11140 68 20 61 6e 20 6f 62 6a 65 63 74 20 69 73 20 74  h an object is t
11150 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61  he.** first para
11160 6d 65 74 65 72 20 74 6f 20 75 73 65 72 2d 64 65  meter to user-de
11170 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
11180 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ons..*/.typedef 
11190 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
111a0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
111b0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
111c0 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e  API3REF:  Bindin
111d0 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
111e0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
111f0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c  **.** In the SQL
11200 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74   strings input t
11210 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
11220 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
11230 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6f 6e   variants,.** on
11240 65 20 6f 72 20 6d 6f 72 65 20 6c 69 74 65 72 61  e or more litera
11250 6c 73 20 63 61 6e 20 62 65 20 72 65 70 6c 61 63  ls can be replac
11260 65 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72  e by a parameter
11270 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   in one of these
11280 0a 2a 2a 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a  .** forms:.**.**
11290 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
112a0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
112b0 2a 20 3c 6c 69 3e 20 20 3a 41 41 41 0a 2a 2a 20  * <li>  :AAA.** 
112c0 3c 6c 69 3e 20 20 40 41 41 41 0a 2a 2a 20 3c 6c  <li>  @AAA.** <l
112d0 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
112e0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70  >.**.** In the p
112f0 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73  arameter forms s
11300 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69  hown above NNN i
11310 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
11320 65 72 61 6c 2c 0a 2a 2a 20 41 41 41 20 69 73 20  eral,.** AAA is 
11330 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
11340 69 64 65 6e 74 69 66 69 65 72 20 61 6e 64 20 56  identifier and V
11350 56 56 20 69 73 20 61 20 76 61 72 69 61 62 6c 65  VV is a variable
11360 20 6e 61 6d 65 20 61 63 63 6f 72 64 69 6e 67 0a   name according.
11370 2a 2a 20 74 6f 20 74 68 65 20 73 79 6e 74 61 78  ** to the syntax
11380 20 72 75 6c 65 73 20 6f 66 20 74 68 65 20 54 43   rules of the TC
11390 4c 20 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61  L programming la
113a0 6e 67 75 61 67 65 2e 0a 2a 2a 20 54 68 65 20 76  nguage..** The v
113b0 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20 70  alues of these p
113c0 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
113d0 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
113e0 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 29 0a 2a  ameter names").*
113f0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
11400 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
11410 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
11420 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
11430 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
11440 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
11450 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
11460 72 6f 75 74 69 6e 65 73 20 61 6c 77 61 79 73 20  routines always 
11470 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
11480 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
11490 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
114a0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
114b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
114c0 5d 20 6f 72 0a 2a 2a 20 69 74 73 20 76 61 72 69  ] or.** its vari
114d0 61 6e 74 73 2e 20 20 54 68 65 20 73 65 63 6f 6e  ants.  The secon
114e0 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  d.** argument is
114f0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
11500 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  e parameter to b
11510 65 20 73 65 74 2e 20 20 54 68 65 20 66 69 72 73  e set.  The firs
11520 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 0a  t parameter has.
11530 2a 2a 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  ** an index of 1
11540 2e 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20  . When the same 
11550 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
11560 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
11570 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 0a 2a  n once, second.*
11580 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  * and subsequent
11590 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
115a0 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
115b0 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
115c0 20 6f 63 63 75 72 72 65 6e 63 65 2e 20 20 54 68   occurrence.  Th
115d0 65 20 69 6e 64 65 78 20 66 6f 72 0a 2a 2a 20 6e  e index for.** n
115e0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
115f0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
11600 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
11610 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
11620 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50  meter_name()] AP
11630 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54  I if desired.  T
11640 68 65 20 69 6e 64 65 78 20 66 6f 72 20 22 3f 4e  he index for "?N
11650 4e 4e 22 0a 2a 2a 20 70 61 72 61 6d 65 74 65 73  NN".** parametes
11660 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
11670 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e   NNN..** The NNN
11680 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
11690 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
116a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
116b0 20 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54   parameter SQLIT
116c0 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e  E_MAX_VARIABLE_N
116d0 55 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20 76  UMBER (default v
116e0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 20 53  alue: 999)..** S
116f0 65 65 20 3c 61 20 68 72 65 66 3d 22 6c 69 6d 69  ee <a href="limi
11700 74 73 2e 68 74 6d 6c 22 3e 6c 69 6d 69 74 73 2e  ts.html">limits.
11710 68 74 6d 6c 3c 2f 61 3e 20 66 6f 72 20 61 64 64  html</a> for add
11720 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
11730 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ion..**.** The t
11740 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
11750 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
11760 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
11770 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ter..**.** In th
11780 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ose.** routines 
11790 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
117a0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
117b0 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75   value is the nu
117c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
117d0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
117e0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
117f0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
11800 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
11810 73 20 69 6e 20 74 68 65 0a 2a 2a 20 73 74 72 69  s in the.** stri
11820 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
11830 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
11840 2e 20 20 54 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  .  The number.**
11850 20 6f 66 20 62 79 74 65 73 20 64 6f 65 73 20 6e   of bytes does n
11860 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
11870 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 61  ero-terminator a
11880 74 20 74 68 65 20 65 6e 64 20 6f 66 20 73 74 72  t the end of str
11890 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ings..** If the 
118a0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
118b0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
118c0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
118d0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75 6d  string is.** num
118e0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
118f0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
11900 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
11910 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72  .** The fifth ar
11920 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
11930 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
11940 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
11950 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
11960 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
11970 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
11980 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
11990 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
119a0 2a 2a 20 74 65 78 74 20 61 66 74 65 72 20 53 51  ** text after SQ
119b0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
119c0 64 20 77 69 74 68 20 69 74 2e 20 20 49 66 20 74  d with it.  If t
119d0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
119e0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 70 65 63  t is the.** spec
119f0 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
11a00 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
11a10 74 68 65 20 6c 69 62 72 61 72 79 20 61 73 73 75  the library assu
11a20 6d 65 73 20 74 68 61 74 20 74 68 65 20 69 6e 66  mes that the inf
11a30 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  ormation.** is i
11a40 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
11a50 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
11a60 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
11a70 65 20 66 72 65 65 64 2e 20 20 49 66 20 74 68 65  e freed.  If the
11a80 0a 2a 2a 20 66 69 66 74 68 20 61 72 67 75 6d 65  .** fifth argume
11a90 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
11aa0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
11ab0 4e 54 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  NT], then SQLite
11ac0 20 6d 61 6b 65 73 20 69 74 73 0a 2a 2a 20 6f 77   makes its.** ow
11ad0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
11ae0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
11af0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74  iately, before t
11b00 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
11b10 2a 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  *().** routine r
11b20 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  eturns..**.** Th
11b30 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
11b40 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
11b50 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
11b60 66 20 6c 65 6e 67 74 68 20 6e 20 74 68 61 74 0a  f length n that.
11b70 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
11b80 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f  h zeros.  A zero
11b90 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
11ba0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
11bb0 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
11bc0 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
11bd0 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  t size) while it
11be0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
11bf0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
11c00 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
11c10 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
11c20 2d 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  -holders for BLO
11c30 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
11c40 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
11c50 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  tten using .** [
11c60 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
11c70 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c  n | increment BL
11c80 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
11c90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
11ca0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
11cb0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
11cc0 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73  lled after.** [s
11cd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
11ce0 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61  2()] (and its va
11cf0 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69  riants) or [sqli
11d00 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64  te3_reset()] and
11d10 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69  .** before [sqli
11d20 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
11d30 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
11d40 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
11d50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
11d60 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e  ] routine..** Un
11d70 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
11d80 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
11d90 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
11da0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
11db0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
11dc0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
11dd0 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66  an error code if
11de0 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65  .** anything goe
11df0 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54  s wrong.  [SQLIT
11e00 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
11e10 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
11e20 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
11e30 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
11e40 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
11e50 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
11e60 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20  alloc fails..** 
11e70 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
11e80 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
11e90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
11ea0 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 76 69  e called on a vi
11eb0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
11ec0 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f   that is the wro
11ed0 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63  ng state or whic
11ee0 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65  h has already be
11ef0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f  en finalized..*/
11f00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
11f10 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
11f20 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
11f30 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
11f40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
11f50 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
11f60 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
11f70 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
11f80 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
11f90 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
11fa0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
11fb0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
11fc0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
11fd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
11fe0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
11ff0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
12000 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
12010 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
12020 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
12030 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
12040 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
12050 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
12060 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
12070 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
12080 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
12090 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
120a0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
120b0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
120c0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
120d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
120e0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
120f0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
12100 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
12110 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
12120 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
12130 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12140 20 4e 75 6d 62 65 72 20 4f 66 20 48 6f 73 74 20   Number Of Host 
12150 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
12160 20 52 65 74 75 72 6e 20 74 68 65 20 6c 61 72 67   Return the larg
12170 65 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  est host paramet
12180 65 72 20 69 6e 64 65 78 20 69 6e 20 74 68 65 20  er index in the 
12190 70 72 65 63 6f 6d 70 69 6c 65 64 20 73 74 61 74  precompiled stat
121a0 65 6d 65 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 61  ement given.** a
121b0 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 2e 20  s the argument. 
121c0 20 57 68 65 6e 20 74 68 65 20 68 6f 73 74 20 70   When the host p
121d0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 6f 66  arameters are of
121e0 20 74 68 65 20 66 6f 72 6d 73 20 6c 69 6b 65 20   the forms like 
121f0 22 3a 41 41 41 22 0a 2a 2a 20 6f 72 20 22 3f 22  ":AAA".** or "?"
12200 2c 20 74 68 65 6e 20 74 68 65 79 20 61 72 65 20  , then they are 
12210 61 73 73 69 67 6e 65 64 20 73 65 71 75 65 6e 74  assigned sequent
12220 69 61 6c 20 69 6e 63 72 65 61 73 69 6e 67 20 6e  ial increasing n
12230 75 6d 62 65 72 73 20 62 65 67 69 6e 6e 69 6e 67  umbers beginning
12240 0a 2a 2a 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f  .** with one, so
12250 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
12260 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
12270 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 2e  r of parameters.
12280 20 20 48 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20    However.** if 
12290 74 68 65 20 73 61 6d 65 20 68 6f 73 74 20 70 61  the same host pa
122a0 72 61 6d 65 74 65 72 20 6e 61 6d 65 20 69 73 20  rameter name is 
122b0 75 73 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  used multiple ti
122c0 6d 65 73 2c 20 65 61 63 68 20 6f 63 63 75 72 72  mes, each occurr
122d0 61 6e 63 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e  ance.** is given
122e0 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72   the same number
122f0 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72  , so the value r
12300 65 74 75 72 6e 65 64 20 69 6e 20 74 68 61 74 20  eturned in that 
12310 63 61 73 65 20 69 73 20 74 68 65 20 6e 75 6d 62  case is the numb
12320 65 72 0a 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20  er.** of unique 
12330 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
12340 61 6d 65 73 2e 20 20 49 66 20 68 6f 73 74 20 70  ames.  If host p
12350 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
12360 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20   form "?NNN".** 
12370 61 72 65 20 75 73 65 64 20 28 77 68 65 72 65 20  are used (where 
12380 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65  NNN is an intege
12390 72 29 20 74 68 65 6e 20 74 68 65 72 65 20 6d 69  r) then there mi
123a0 67 68 74 20 62 65 20 67 61 70 73 20 69 6e 20 74  ght be gaps in t
123b0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 69 6e 67 20  he.** numbering 
123c0 61 6e 64 20 74 68 65 20 76 61 6c 75 65 20 72 65  and the value re
123d0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 69  turned by this i
123e0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
123f0 69 6e 64 65 78 20 6f 66 20 74 68 65 0a 2a 2a 20  index of the.** 
12400 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 77  host parameter w
12410 69 74 68 20 74 68 65 20 6c 61 72 67 65 73 74 20  ith the largest 
12420 69 6e 64 65 78 20 76 61 6c 75 65 2e 0a 2a 2a 0a  index value..**.
12430 2a 2a 20 54 68 65 20 70 72 65 70 61 72 65 64 20  ** The prepared 
12440 73 74 61 74 65 6d 65 6e 74 20 6d 75 73 74 20 6e  statement must n
12450 6f 74 20 62 65 20 5b 73 71 6c 69 74 65 33 5f 66  ot be [sqlite3_f
12460 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
12470 7a 65 64 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  zed].** prior to
12480 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
12490 74 75 72 6e 6e 69 6e 67 2e 20 20 4f 74 68 65 72  turnning.  Other
124a0 77 69 73 65 20 74 68 65 20 72 65 73 75 6c 74 73  wise the results
124b0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a   are undefined.*
124c0 2a 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  * and probably u
124d0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 69  ndesirable..*/.i
124e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
124f0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
12500 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
12510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12520 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
12530 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
12540 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
12550 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
12560 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  o the name of th
12570 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
12580 20 69 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74   in a .** [sqlit
12590 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
125a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
125b0 2a 20 48 6f 73 74 20 70 61 72 61 6d 65 74 65 72  * Host parameter
125c0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a  s of the form ":
125d0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
125e0 72 20 22 24 56 56 56 22 20 68 61 76 65 20 61 20  r "$VVV" have a 
125f0 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73  name.** which is
12600 20 74 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41   the string ":AA
12610 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
12620 22 24 56 56 56 22 2e 20 20 0a 2a 2a 20 49 6e 20  "$VVV".  .** In 
12630 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
12640 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
12650 22 24 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73  "$" or "@".** is
12660 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
12670 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  t of the name..*
12680 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20  * Parameters of 
12690 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20  the form "?" or 
126a0 22 3f 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e  "?NNN" have no n
126b0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ame..**.** The f
126c0 69 72 73 74 20 62 6f 75 6e 64 20 70 61 72 61 6d  irst bound param
126d0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
126e0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
126f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75  *.** If the valu
12700 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e n is out of ra
12710 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d  nge or if the n-
12720 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
12730 6e 61 6d 65 6c 65 73 73 2c 0a 2a 2a 20 74 68 65  nameless,.** the
12740 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
12750 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65  ed.  The returne
12760 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
12770 79 73 20 69 6e 20 74 68 65 0a 2a 2a 20 55 54 46  ys in the.** UTF
12780 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
12790 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
127a0 72 61 6d 65 74 65 72 20 77 61 73 20 6f 72 69 67  rameter was orig
127b0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
127c0 0a 2a 2a 20 61 73 20 55 54 46 2d 31 36 20 69 6e  .** as UTF-16 in
127d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
127e0 65 31 36 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  e16()] or [sqlit
127f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
12800 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
12810 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
12820 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
12830 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
12840 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
12850 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
12860 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
12870 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
12880 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
12890 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
128a0 20 6f 66 20 61 20 68 6f 73 74 20 70 61 72 61 6d   of a host param
128b0 65 74 65 72 20 77 69 74 68 20 74 68 65 20 67 69  eter with the gi
128c0 76 65 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65  ven name..** The
128d0 20 6e 61 6d 65 20 6d 75 73 74 20 6d 61 74 63 68   name must match
128e0 20 65 78 61 63 74 6c 79 2e 20 20 49 66 20 6e 6f   exactly.  If no
128f0 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
12900 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 20 69  the given name i
12910 73 20 0a 2a 2a 20 66 6f 75 6e 64 2c 20 72 65 74  s .** found, ret
12920 75 72 6e 20 30 2e 20 20 50 61 72 61 6d 65 74 65  urn 0.  Paramete
12930 72 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  r names must be 
12940 55 54 46 38 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  UTF8..*/.int sql
12950 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
12960 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
12970 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
12980 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
12990 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
129a0 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
129b0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
129c0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 43  tatement.**.** C
129d0 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
129e0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
129f0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
12a00 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ()] does not.** 
12a10 72 65 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74  reset the [sqlit
12a20 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
12a30 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a  indings] on a .*
12a40 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
12a50 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
12a60 6d 65 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73  ment].  Use this
12a70 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72   routine to.** r
12a80 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
12a90 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
12aa0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12ab0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
12ac0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
12ad0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12ae0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
12af0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
12b00 65 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  et.**.** Return 
12b10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
12b20 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
12b30 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
12b40 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   by the .** [sql
12b50 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70  ite3_stmt | comp
12b60 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
12b70 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  nt]. This routin
12b80 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69  e returns 0.** i
12b90 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
12ba0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
12bb0 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
12bc0 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65   data (for .** e
12bd0 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45  xample an UPDATE
12be0 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
12bf0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
12c00 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
12c10 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
12c20 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
12c30 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
12c40 65 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  et.**.** These r
12c50 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
12c60 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
12c70 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
12c80 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
12c90 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
12ca0 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
12cb0 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  nt.  The sqlite3
12cc0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
12cd0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
12ce0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
12cf0 20 61 20 55 54 46 38 20 73 74 72 69 6e 67 20 61   a UTF8 string a
12d00 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
12d10 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 72 65  n_name16().** re
12d20 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
12d30 74 6f 20 61 20 55 54 46 31 36 20 73 74 72 69 6e  to a UTF16 strin
12d40 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  g.  The first pa
12d50 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
12d60 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
12d70 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
12d80 6d 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c 65  ment] that imple
12d90 6d 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54  ments the SELECT
12da0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
12db0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
12dc0 74 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75 6d  ter is the colum
12dd0 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c  n number.  The l
12de0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
12df0 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a  is.** number 0..
12e00 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  **.** The return
12e10 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
12e20 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
12e30 20 65 69 74 68 65 72 20 74 68 65 20 0a 2a 2a 20   either the .** 
12e40 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
12e50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12e60 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
12e70 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
12e80 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75  alize()].** or u
12e90 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
12ea0 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
12eb0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
12ec0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
12ed0 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  6().** on the sa
12ee0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
12ef0 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
12f00 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
12f10 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
12f20 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
12f30 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
12f40 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
12f50 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
12f60 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
12f70 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
12f80 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
12f90 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
12fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
12fb0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
12fc0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
12fd0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
12fe0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
12ff0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
13000 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
13010 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
13020 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
13030 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73  esult.**.** Thes
13040 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
13050 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
13060 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c  termine what col
13070 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74  umn of what.** t
13080 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61  able in which da
13090 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20  tabase a result 
130a0 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  of a SELECT stat
130b0 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d  ement comes from
130c0 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  ..** The name of
130d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
130e0 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
130f0 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
13100 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
13110 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 73 74  UTF8 or UTF16 st
13120 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61  ring.  The _data
13130 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
13140 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
13150 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
13160 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
13170 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
13180 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
13190 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
131a0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
131b0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  olumn name..** T
131c0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
131d0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
131e0 6c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  l.** the [sqlite
131f0 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  3_stmt | prepare
13200 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
13210 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
13220 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
13230 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
13240 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
13250 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
13260 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
13270 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
13280 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ing..**.** The n
13290 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
132a0 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
132b0 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
132c0 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
132d0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
132e0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  olumn..**.** The
132f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13300 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  to the following
13310 20 63 61 6c 6c 73 20 69 73 20 61 20 0a 2a 2a 20   calls is a .** 
13320 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
13330 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
13340 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73  tement]..** Thes
13350 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
13360 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
13370 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c  bout the Nth col
13380 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
13390 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
133a0 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
133b0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
133c0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
133d0 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  * If the Nth col
133e0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
133f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
13400 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a   an expression.*
13410 2a 20 6f 72 20 73 75 62 71 75 65 72 79 20 61 6e  * or subquery an
13420 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
13430 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
13440 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
13450 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e  ions.** return N
13460 55 4c 4c 2e 20 4f 74 68 65 72 77 69 73 65 2c 20  ULL. Otherwise, 
13470 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
13480 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
13490 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
134a0 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  e, table and col
134b0 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
134c0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
134d0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
134e0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74  om..**.** As wit
134f0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
13500 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70  te APIs, those p
13510 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31  ostfixed with "1
13520 36 22 20 72 65 74 75 72 6e 20 55 54 46 2d 31 36  6" return UTF-16
13530 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 73 74 72 69  .** encoded stri
13540 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66  ngs, the other f
13550 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
13560 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  UTF-8..**.** The
13570 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
13580 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
13590 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
135a0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
135b0 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  .** SQLITE_ENABL
135c0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
135d0 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  A preprocessor s
135e0 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
135f0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
13600 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
13610 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
13620 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
13630 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
13640 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
13650 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
13660 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
13670 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
13680 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
13690 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
136a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
136b0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
136c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
136d0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
136e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
136f0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
13700 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
13710 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
13720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
13730 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
13740 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
13750 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
13760 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
13770 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
13780 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
13790 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
137a0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
137b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
137c0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
137d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
137e0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
137f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
13800 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13810 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
13820 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
13830 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Result.**.** The
13840 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13850 20 69 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   is a [sqlite3_s
13860 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53  tmt | compiled S
13870 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a  QL statement]. .
13880 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
13890 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54  ment is a SELECT
138a0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
138b0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
138c0 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65   the .** returne
138d0 64 20 72 65 73 75 6c 74 20 73 65 74 20 20 6f 66  d result set  of
138e0 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20   that SELECT is 
138f0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
13900 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
13910 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
13920 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
13930 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
13940 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
13950 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20  is returned. If 
13960 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
13970 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
13980 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
13990 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
139a0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
139b0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
139c0 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
139d0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
139e0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
139f0 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d. For example, 
13a00 69 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  in.** the databa
13a10 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
13a20 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
13a30 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
13a40 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c  .** And the foll
13a50 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
13a60 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
13a70 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
13a80 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
13a90 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   Then this routi
13aa0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
13ab0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
13ac0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
13ad0 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f  ond.** result co
13ae0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
13af0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
13b00 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
13b10 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28  sult column.** (
13b20 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  i==0)..**.** SQL
13b30 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
13b40 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
13b50 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75  .  So just becau
13b60 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
13b70 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
13b80 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
13b90 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
13ba0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
13bb0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
13bc0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
13bd0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
13be0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
13bf0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
13c00 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
13c10 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
13c20 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a  t static.  Type.
13c30 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
13c40 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
13c50 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
13c60 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
13c70 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
13c80 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
13c90 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
13ca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
13cb0 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
13cc0 6d 74 20 2a 2c 20 69 6e 74 20 69 29 3b 0a 63 6f  mt *, int i);.co
13cd0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
13ce0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
13cf0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
13d00 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20  *,int);../* .** 
13d10 43 41 50 49 33 52 45 46 3a 20 20 45 76 61 6c 75  CAPI3REF:  Evalu
13d20 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
13d30 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
13d40 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d   an [sqlite3_stm
13d50 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  t | SQL statemen
13d60 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
13d70 61 72 65 64 20 77 69 74 68 20 61 20 63 61 6c 6c  ared with a call
13d80 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b 73  .** to either [s
13d90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
13da0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
13db0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
13dc0 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a   or to one of.**
13dd0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
13de0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
13df0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
13e00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
13e10 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  ()],.** then thi
13e20 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  s function must 
13e30 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
13e40 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
13e50 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a 20  valuate the .** 
13e60 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
13e70 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
13e80 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
13e90 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74 65  this sqlite3_ste
13ea0 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
13eb0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
13ec0 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
13ed0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
13ee0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
13ef0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
13f00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
13f10 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
13f20 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
13f30 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
13f40 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
13f50 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
13f60 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
13f70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
13f80 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
13f90 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
13fa0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
13fb0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
13fc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
13fd0 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
13fe0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
13ff0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
14000 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  pported..**.** I
14010 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69 6e 74  n the lagacy int
14020 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
14030 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
14040 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
14050 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49  BUSY], .** [SQLI
14060 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
14070 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
14080 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
14090 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57  TE_MISUSE]..** W
140a0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
140b0 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
140c0 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45  he other [SQLITE
140d0 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
140e0 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  e].** or [SQLITE
140f0 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
14100 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
14110 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  de] might be ret
14120 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c  urned as.** well
14130 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
14140 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
14150 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
14160 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
14170 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
14180 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
14190 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
141a0 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65  its job.  If the
141b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
141c0 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63  COMMIT.** or occ
141d0 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
141e0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
141f0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
14200 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
14210 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
14220 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
14230 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61  s not a COMMIT a
14240 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
14250 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
14260 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
14270 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
14280 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
14290 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
142a0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
142b0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
142c0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
142d0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
142e0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
142f0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
14300 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
14310 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
14320 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
14330 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
14340 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
14350 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
14360 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
14370 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
14380 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
14390 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
143a0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
143b0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
143c0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
143d0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
143e0 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51  ta, then .** [SQ
143f0 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65 74  LITE_ROW] is ret
14400 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
14410 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
14420 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f  a is ready.** fo
14430 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
14440 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  the caller. The 
14450 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
14460 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  cessed using.** 
14470 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
14480 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e  umn_int | column
14490 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
144a0 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
144b0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
144c0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
144d0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
144e0 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b  f data..** .** [
144f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
14500 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
14510 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
14520 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
14530 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
14540 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
14550 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
14560 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
14570 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
14580 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
14590 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
145a0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
145b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
145c0 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65  ..** With the le
145d0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
145e0 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
145f0 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d  error code (exam
14600 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple:.** [SQLITE_
14610 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
14620 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
14630 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
14640 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
14650 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
14660 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
14670 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
14680 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
14690 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
146a0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
146b0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
146c0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
146d0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
146e0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
146f0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
14700 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
14710 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
14720 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
14730 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
14740 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
14750 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
14760 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
14770 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65 33  ed on a [sqlite3
14780 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
14790 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
147a0 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
147b0 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
147c0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
147d0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
147e0 61 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69  at had .** previ
147f0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
14800 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
14810 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
14820 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
14830 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
14840 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
14850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
14860 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
14870 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
14880 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
14890 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
148a0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
148b0 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
148c0 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20  :</b>.** In the 
148d0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
148e0 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  , .** the sqlite
148f0 33 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c 77  3_step() API alw
14900 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
14910 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
14920 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
14930 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
14940 6e 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ny error other t
14950 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
14960 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45  ].** and [SQLITE
14970 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
14980 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  ust call [sqlite
14990 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
149a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
149b0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
149c0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
149d0 65 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53  e specific.** [S
149e0 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65  QLITE_ERROR | re
149f0 73 75 6c 74 20 63 6f 64 65 73 5d 20 74 68 61 74  sult codes] that
14a00 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
14a10 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
14a20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
14a30 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
14a40 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
14a50 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
14a60 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
14a70 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
14a80 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
14a90 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
14aa0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
14ab0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
14ac0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
14ad0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
14ae0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
14af0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
14b00 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
14b10 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
14b20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
14b30 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a  )], then the .**
14b40 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
14b50 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
14b60 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65  esult codes] are
14b70 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
14b80 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
14b90 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
14ba0 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
14bb0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
14bc0 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
14bd0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
14be0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
14bf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a  ** CAPI3REF:.**.
14c00 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75  ** Return the nu
14c10 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
14c20 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
14c30 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
14c40 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  set..**.** After
14c50 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
14c60 74 65 33 5f 73 74 65 70 28 29 5d 20 74 68 61 74  te3_step()] that
14c70 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
14c80 5f 52 4f 57 5d 2c 20 74 68 69 73 20 72 6f 75 74  _ROW], this rout
14c90 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  ine.** will retu
14ca0 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  rn the same valu
14cb0 65 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65  e as the [sqlite
14cc0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
14cd0 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41  ] function..** A
14ce0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
14cf0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
14d00 65 64 20 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f  ed an [SQLITE_DO
14d10 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  NE], [SQLITE_BUS
14d20 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c  Y], or.** a [SQL
14d30 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f  ITE_ERROR | erro
14d40 72 20 63 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f  r code], or befo
14d50 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
14d60 28 29 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a  ()] has been .**
14d70 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b   called on the [
14d80 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
14d90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
14da0 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  t] for the first
14db0 20 74 69 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72   time,.** this r
14dc0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
14dd0 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ero..*/.int sqli
14de0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
14df0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
14e00 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
14e10 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
14e20 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a  l Datatypes.**.*
14e30 2a 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  * Every value in
14e40 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
14e50 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
14e60 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
14e70 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
14e80 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
14e90 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
14ea0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
14eb0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
14ec0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
14ed0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
14ee0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
14ef0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ul>.**.** These 
14f00 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
14f10 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
14f20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
14f30 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
14f40 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
14f50 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
14f60 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
14f70 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
14f80 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
14f90 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
14fa0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
14fb0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
14fc0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
14fd0 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
14fe0 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
14ff0 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
15000 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  T not.** SQLITE_
15010 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
15020 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
15030 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
15040 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
15050 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
15060 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
15070 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
15080 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
15090 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
150a0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
150b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
150c0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
150d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
150e0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
150f0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
15100 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  lts Values From 
15110 41 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68  A Query.**.** Th
15120 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
15130 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
15140 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67 6c  about.** a singl
15150 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
15160 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72  current result r
15170 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
15180 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65  In every.** case
15190 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
151a0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
151b0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   to the .** [sql
151c0 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
151d0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
151e0 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c  is being.** eval
151f0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
15200 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20  te3_stmt*] that 
15210 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
15220 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  m .** [sqlite3_p
15230 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
15240 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
15250 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20  nts) and.** the 
15260 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15270 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
15280 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
15290 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
152a0 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72   .** should be r
152b0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65  eturned.  The le
152c0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  ft-most column o
152d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
152e0 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e 64 65 78  .** has an index
152f0 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20   of 0..**.** If 
15300 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
15310 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
15320 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
15330 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
15340 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e  he.** the column
15350 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
15360 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
15370 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
15380 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69   .** These routi
15390 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
153a0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
153b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
153c0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
153d0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
153e0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
153f0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
15400 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
15410 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
15420 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73 20  finalize()] has 
15430 62 65 65 6e 20 63 61 6c 6c 20 73 75 62 73 65 71  been call subseq
15440 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
15450 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
15460 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
15470 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
15480 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
15490 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
154a0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
154b0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
154c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
154d0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
154e0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
154f0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
15500 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
15510 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
15520 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
15530 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
15540 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
15550 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
15560 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
15570 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
15580 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
15590 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
155a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
155b0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 20   are undefined. 
155c0 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69   .**.** The sqli
155d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
155e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
155f0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  s .** [SQLITE_IN
15600 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
15610 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
15620 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
15630 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
15640 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
15650 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
15660 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
15670 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
15680 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
15690 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
156a0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
156b0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
156c0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
156d0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
156e0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
156f0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
15700 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
15710 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
15720 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
15730 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
15740 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
15750 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
15760 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
15770 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
15780 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
15790 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
157a0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
157b0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
157c0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
157d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
157e0 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
157f0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
15800 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
15810 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
15820 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
15830 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
15840 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
15850 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
15860 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
15870 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
15880 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
15890 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
158a0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
158b0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
158c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
158d0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
158e0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
158f0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
15900 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
15910 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  bytes..** If the
15920 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
15930 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
15940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
15950 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
15960 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
15970 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
15980 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
15990 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
159a0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
159b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
159c0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
159d0 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
159e0 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
159f0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
15a00 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
15a10 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
15a20 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72  tring.  For clar
15a30 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
15a40 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
15a50 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
15a60 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
15a70 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
15a80 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
15a90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
15aa0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
15ab0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
15ac0 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
15ad0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
15ae0 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
15af0 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
15b00 36 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46  6 instead of UTF
15b10 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72  -8.  .** The zer
15b20 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
15b30 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
15b40 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
15b50 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
15b60 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
15b70 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
15b80 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
15b90 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
15ba0 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
15bb0 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
15bc0 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
15bd0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
15be0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
15bf0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
15c00 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
15c10 61 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65 20 63  ally to do the c
15c20 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74  onversion.** aut
15c30 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
15c40 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
15c50 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
15c60 76 65 72 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a  versions that.**
15c70 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
15c80 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
15c90 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
15ca0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
15cb0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
15cc0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
15cd0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
15ce0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
15cf0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
15d00 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
15d10 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
15d20 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
15d30 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
15d40 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
15d50 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
15d60 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
15d70 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
15d80 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
15d90 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
15da0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
15db0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
15dc0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
15dd0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
15de0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
15df0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
15e00 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
15e10 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
15e20 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
15e30 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
15e40 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
15e50 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
15e60 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
15e70 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
15e80 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
15e90 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72 20 49  d> Same as for I
15ea0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
15eb0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
15ec0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
15ed0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
15ee0 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
15ef0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
15f00 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
15f10 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
15f20 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
15f30 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
15f40 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
15f50 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
15f60 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
15f70 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
15f80 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
15f90 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
15fa0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
15fb0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
15fc0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
15fd0 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
15fe0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
15ff0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
16000 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
16010 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
16020 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
16030 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
16040 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
16050 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
16060 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
16070 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
16080 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
16090 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
160a0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
160b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
160c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
160d0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
160e0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
160f0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
16100 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
16110 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
16120 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
16130 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
16140 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
16150 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
16160 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
16170 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
16180 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
16190 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
161a0 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e 74 20  * on equavalent 
161b0 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
161c0 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
161d0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
161e0 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
161f0 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
16200 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
16210 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
16220 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
16230 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
16240 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
16250 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
16260 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
16270 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
16280 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
16290 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
162a0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
162b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
162c0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
162d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
162e0 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
162f0 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f  ted. .** Type co
16300 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
16310 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
16320 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
16330 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
16340 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
16350 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e   <ul>.** <li><p>
16360 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
16370 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
16380 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
16390 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20 20  mn_text() .**   
163a0 20 20 20 20 20 20 20 6f 72 20 73 71 6c 69 74 65         or sqlite
163b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
163c0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
163d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
163e0 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 20 20  might.**        
163f0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
16400 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
16410 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  .</p></li>.**.**
16420 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
16430 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
16440 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
16450 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
16460 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
16470 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
16480 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
16490 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
164a0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
164b0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
164c0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
164d0 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  </p></li>.**.** 
164e0 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69  <li><p>  The ini
164f0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
16500 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
16510 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
16520 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
16530 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
16540 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
16550 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
16560 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
16570 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  erted.**        
16580 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c    to UTF-8.</p><
16590 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
165a0 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20  .** Conversions 
165b0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
165c0 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
165d0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
165e0 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
165f0 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
16600 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
16610 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
16620 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
16630 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
16640 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
16650 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20  inter points to 
16660 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
16670 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
16680 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
16690 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
166a0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
166b0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
166c0 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 20 69 73  t sometime it is
166d0 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
166e0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
166f0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
16700 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
16710 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ed.  .**.** The 
16720 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
16730 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
16740 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
16750 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
16760 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
16770 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
16780 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a  s:.**.**  <ul>.*
16790 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
167a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
167b0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
167c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
167d0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
167e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
167f0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
16800 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
16810 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
16820 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
16830 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
16840 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
16850 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
16860 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a  /li>.**  </ul>.*
16870 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
16880 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
16890 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
168a0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  umn_text(), sqli
168b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
168c0 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ),.** or sqlite3
168d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
168e0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
168f0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
16900 74 68 65 20 64 65 73 69 72 65 64 0a 2a 2a 20 66  the desired.** f
16910 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
16920 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
16930 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 73 71 6c  n_bytes() or sql
16940 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
16950 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64  s16() to.** find
16960 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
16970 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
16980 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c   mix call to sql
16990 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
169a0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
169b0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
169c0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
169d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
169e0 73 31 36 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e  s16().  And do n
169f0 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20  ot.** mix calls 
16a00 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
16a10 6e 5f 74 65 78 74 31 36 28 29 20 77 69 74 68 20  n_text16() with 
16a20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
16a30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
16a40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
16a50 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
16a60 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
16a70 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
16a80 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
16a90 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
16aa0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
16ab0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
16ac0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
16ad0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
16ae0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
16af0 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70  .  The memory sp
16b00 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
16b10 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
16b20 62 6c 6f 62 73 20 69 73 20 66 72 65 65 64 20 61  blobs is freed a
16b30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
16b40 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
16b50 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
16b60 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
16b70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
16b80 29 5d 2c 20 5b 73 71 6c 69 74 65 5f 63 6f 6c 75  )], [sqlite_colu
16b90 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
16ba0 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74   into .** [sqlit
16bb0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
16bc0 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  * If a memory al
16bd0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
16be0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
16bf0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
16c00 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
16c10 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
16c20 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
16c30 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
16c40 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
16c50 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
16c60 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
16c70 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
16c80 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
16c90 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
16ca0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
16cb0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
16cc0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
16cd0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
16ce0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
16cf0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
16d00 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
16d10 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
16d20 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
16d30 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
16d40 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
16d50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
16d60 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
16d70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
16d80 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
16d90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
16da0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
16db0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
16dc0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
16dd0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
16de0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
16df0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
16e00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
16e10 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
16e20 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
16e30 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
16e40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
16e50 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
16e60 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
16e70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
16e80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
16e90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
16ea0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
16eb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
16ec0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
16ed0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
16ee0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
16ef0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
16f00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
16f10 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
16f20 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
16f30 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
16f40 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
16f50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
16f60 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
16f70 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
16f80 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20  to delete a .** 
16f90 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
16fa0 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
16fb0 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 20  tement]. If the 
16fc0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
16fd0 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73   executed succes
16fe0 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65  sfully, or not e
16ff0 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20  xecuted at all, 
17000 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  then SQLITE_OK i
17010 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
17020 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  f execution of t
17030 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69  he statement fai
17040 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20  led then an .** 
17050 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
17060 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b  error code] or [
17070 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
17080 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72  D | extended err
17090 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72  or code].** is r
170a0 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20  eturned. .**.** 
170b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
170c0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
170d0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74  y point during t
170e0 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
170f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17100 73 74 6d 74 20 7c 20 76 69 72 74 75 61 6c 20 6d  stmt | virtual m
17110 61 63 68 69 6e 65 5d 2e 20 20 49 66 20 74 68 65  achine].  If the
17120 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
17130 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d   has not .** com
17140 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
17150 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   when this routi
17160 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  ne is called, th
17170 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e  at is like.** en
17180 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72  countering an er
17190 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 72  ror or an interr
171a0 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c 69  upt.  (See [sqli
171b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
171c0 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74  .) .** Incomplet
171d0 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65  e updates may be
171e0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64   rolled back and
171f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61   transactions ca
17200 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 65  ncelled,  .** de
17210 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
17220 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e  ircumstances, an
17230 64 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  d the .** [SQLIT
17240 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74  E_ERROR | result
17250 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
17260 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
17270 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ABORT]..*/.int s
17280 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
17290 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
172a0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
172b0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
172c0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
172d0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
172e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
172f0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
17300 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
17310 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
17320 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51  mt | compiled SQ
17330 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  L statement] obj
17340 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  ect..** back to 
17350 69 74 27 73 20 69 6e 69 74 69 61 6c 20 73 74 61  it's initial sta
17360 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
17370 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
17380 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
17390 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
173a0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
173b0 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
173c0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
173d0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
173e0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
173f0 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
17400 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
17410 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
17420 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
17430 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
17440 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
17450 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
17460 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
17470 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
17480 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
17490 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  QL Functions.**.
174a0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
174b0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 61   two functions a
174c0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
174d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
174e0 61 67 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72  aggregates.** or
174f0 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
17500 20 62 65 68 61 76 69 6f 72 20 6f 66 20 65 78 69   behavior of exi
17510 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
17520 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
17530 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69 66 66 65  s.  The.** diffe
17540 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77 65  rence only betwe
17550 65 6e 20 74 68 65 20 74 77 6f 20 69 73 20 74 68  en the two is th
17560 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  at the second pa
17570 72 61 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20  rameter, the.** 
17580 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61  name of the (sca
17590 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72  lar) function or
175a0 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65   aggregate, is e
175b0 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20  ncoded in UTF-8 
175c0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  for.** sqlite3_c
175d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
175e0 20 61 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 20   and UTF-16 for 
175f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
17600 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  unction16()..**.
17610 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17620 75 6d 65 6e 74 20 69 73 20 74 68 65 20 5b 73 71  ument is the [sq
17630 6c 69 74 65 33 20 7c 20 64 61 74 61 62 61 73 65  lite3 | database
17640 20 68 61 6e 64 6c 65 5d 20 74 68 61 74 20 68 6f   handle] that ho
17650 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  lds the.** SQL f
17660 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
17670 67 61 74 65 20 69 73 20 74 6f 20 62 65 20 61 64  gate is to be ad
17680 64 65 64 20 6f 72 20 72 65 64 65 66 69 6e 65 64  ded or redefined
17690 2e 20 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  . If a single.**
176a0 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f   program uses mo
176b0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
176c0 62 61 73 65 20 68 61 6e 64 6c 65 20 69 6e 74 65  base handle inte
176d0 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c  rnally, then SQL
176e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  .** functions or
176f0 20 61 67 67 72 65 67 61 74 65 73 20 6d 75 73 74   aggregates must
17700 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69   be added indivi
17710 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 64  dually to each d
17720 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c  atabase.** handl
17730 65 20 77 69 74 68 20 77 68 69 63 68 20 74 68 65  e with which the
17740 79 20 77 69 6c 6c 20 62 65 20 75 73 65 64 2e 0a  y will be used..
17750 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
17760 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
17770 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
17780 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
17790 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20 72   created.** or r
177a0 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  edefined..** The
177b0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
177c0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
177d0 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63  o 255 bytes, exc
177e0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 0a 2a  lusive of the .*
177f0 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  * zero-terminato
17800 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  r.  Note that th
17810 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69  e name length li
17820 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c  mit is in bytes,
17830 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65   not.** characte
17840 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74  rs.  Any attempt
17850 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
17860 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
17870 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
17880 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 53 51   result in an SQ
17890 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72 6f 72  LITE_ERROR error
178a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
178b0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
178c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
178d0 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
178e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
178f0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
17900 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61  es. If this para
17910 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
17920 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  e, then the SQL 
17930 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
17940 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
17950 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
17960 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
17970 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
17980 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
17990 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20   specifies what 
179a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
179b0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
179c0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
179d0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
179e0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
179f0 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63  s.  Any SQL func
17a00 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
17a10 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62  ion should be ab
17a20 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f  le to work.** wo
17a30 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  rk with UTF-8, U
17a40 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
17a50 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
17a60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
17a70 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
17a80 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
17a90 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
17aa0 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20  another.  It is 
17ab0 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e  allowed to.** in
17ac0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
17ad0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
17ae0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
17af0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
17b00 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
17b10 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
17b20 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
17b30 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
17b40 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
17b50 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69   When multiple i
17b60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
17b70 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
17b80 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
17b90 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
17ba0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
17bb0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
17bc0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
17bd0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
17be0 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
17bf0 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
17c00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
17c10 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
17c20 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74 20 65  e what.** text e
17c30 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
17c40 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
17c50 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
17c60 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 41   be.** [SQLITE_A
17c70 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  NY]..**.** The f
17c80 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
17c90 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
17ca0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
17cb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
17cc0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 63  f the function c
17cd0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
17ce0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
17cf0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
17d00 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a  _user_data()]..*
17d10 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68  *.** The seventh
17d20 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e  , eighth and nin
17d30 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
17d40 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
17d50 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
17d60 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
17d70 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
17d80 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
17d90 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
17da0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
17db0 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75   A scalar SQL fu
17dc0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
17dd0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
17de0 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 75 6e  n of.** the xFun
17df0 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c  c callback only,
17e00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73   NULL pointers s
17e10 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
17e20 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a 2a 20  as the xStep.** 
17e30 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72 61 6d  and xFinal param
17e40 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67  eters. An aggreg
17e50 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
17e60 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
17e70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
17e80 66 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  f xStep and xFin
17e90 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75  al and NULL shou
17ea0 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  ld be passed for
17eb0 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74   xFunc. To delet
17ec0 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69 6e 67  e an.** existing
17ed0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
17ee0 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
17ef0 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68   NULL for all th
17f00 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
17f10 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
17f20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
17f30 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
17f40 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
17f50 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
17f60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
17f70 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
17f80 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
17f90 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
17fa0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
17fb0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
17fc0 70 65 72 66 65 72 72 65 64 20 74 65 78 74 20 65  perferred text e
17fd0 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74  ncodings.  SQLit
17fe0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
17ff0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
18000 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
18010 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
18020 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
18030 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
18040 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
18050 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
18060 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 2c  on(.  sqlite3 *,
18070 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
18080 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
18090 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
180a0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
180b0 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  *,.  void (*xFun
180c0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
180d0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
180e0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
180f0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
18100 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
18110 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
18120 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
18130 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
18140 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
18150 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
18160 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
18170 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
18180 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
18190 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
181a0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
181b0 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  d*,.  void (*xFu
181c0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
181d0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
181e0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
181f0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
18200 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
18210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
18220 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
18230 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
18240 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  xt*).);../*.** C
18250 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
18260 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
18270 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
18280 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
18290 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
182a0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
182b0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
182c0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
182d0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
182e0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
182f0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
18300 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
18310 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
18320 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
18330 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
18340 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
18350 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
18360 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
18370 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
18380 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
18390 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
183a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
183b0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
183c0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
183d0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
183e0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
183f0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
18400 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
18410 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e  EF: Obsolete Fun
18420 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
18430 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
18440 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74   all now obsolet
18450 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  e.  In order to 
18460 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
18470 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
18480 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
18490 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65  ode, we continue
184a0 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74   to support.** t
184b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
184c0 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65   However, new de
184d0 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63  velopment projec
184e0 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ts should avoid.
184f0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
18500 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
18510 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
18520 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
18530 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
18540 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
18550 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
18560 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68  tell you want th
18570 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ey do..*/.int sq
18580 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
18590 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
185a0 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  ntext*);.int sql
185b0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
185c0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
185d0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
185e0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
185f0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
18600 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71  3_stmt*);.int sq
18610 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
18620 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64  over(void);.void
18630 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
18640 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 0a  cleanup(void);..
18650 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18660 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
18670 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
18680 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
18690 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
186a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
186b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
186c0 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
186d0 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
186e0 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
186f0 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
18700 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
18710 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
18720 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
18730 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
18740 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
18750 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
18760 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
18770 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
18780 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
18790 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
187a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
187b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
187c0 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
187d0 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
187e0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
187f0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
18800 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34  egates..** The 4
18810 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
18820 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
18830 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
18840 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 73  ointers to.** [s
18850 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
18860 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
18870 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
18880 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
18890 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
188a0 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
188b0 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
188c0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
188d0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
188e0 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
188f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
18900 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
18910 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
18920 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
18930 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a  orresponding .**
18940 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
18950 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
18960 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65  column_* routine
18970 73 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 0a  s] except that .
18980 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
18990 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
189a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
189b0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
189c0 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
189d0 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
189e0 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
189f0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
18a00 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
18a10 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
18a20 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
18a30 63 74 73 20 61 20 55 54 46 31 36 20 73 74 72 69  cts a UTF16 stri
18a40 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
18a50 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
18a60 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
18a70 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ne.  The.** sqli
18a80 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
18a90 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
18aa0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
18ab0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
18ac0 65 78 74 72 61 63 74 20 55 54 46 31 36 20 73 74  extract UTF16 st
18ad0 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
18ae0 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
18af0 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
18b00 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
18b10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
18b20 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
18b30 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
18b40 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
18b50 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
18b60 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
18b70 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
18b80 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
18b90 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
18ba0 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
18bb0 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
18bc0 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
18bd0 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
18be0 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
18bf0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
18c00 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 72 64 65 72  mation (in order
18c10 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68 65  .** words if the
18c20 20 76 61 6c 75 65 20 69 73 20 6f 72 69 67 69 6e   value is origin
18c30 61 6c 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  al a string that
18c40 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
18c50 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 69 74  mber).** then it
18c60 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72   is done.  Other
18c70 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
18c80 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  on occurs.  The 
18c90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
18ca0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
18cb0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
18cc0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
18cd0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
18ce0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
18cf0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
18d00 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
18d10 20 74 68 61 74 0a 2a 2a 20 69 73 20 72 65 74 75   that.** is retu
18d20 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
18d30 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
18d40 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
18d50 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
18d60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
18d70 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
18d80 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
18d90 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
18da0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
18db0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
18dc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
18dd0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
18de0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
18df0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
18e00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
18e10 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].  .**.** These
18e20 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
18e30 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
18e40 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
18e50 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
18e60 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
18e70 65 64 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  ed the sqlite3_v
18e80 61 6c 75 65 2a 20 70 61 72 61 6d 65 74 65 72 73  alue* parameters
18e90 2e 0a 2a 2a 20 4f 72 2c 20 69 66 20 74 68 65 20  ..** Or, if the 
18ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 61  sqlite3_value* a
18eb0 72 67 75 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72  rgument comes fr
18ec0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
18ed0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 0a  column_value()].
18ee0 2a 2a 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  ** interface, th
18ef0 65 6e 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  en these routine
18f00 73 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c  s should be call
18f10 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
18f20 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 74 20   thread.** that 
18f30 72 61 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  ran [sqlite3_col
18f40 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2f  umn_value()]..*/
18f50 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
18f60 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
18f70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
18f80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
18f90 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
18fa0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
18fb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
18fc0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
18fd0 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
18fe0 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
18ff0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
19000 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
19010 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
19020 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
19030 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
19040 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
19050 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
19060 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
19070 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
19080 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
19090 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
190a0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
190b0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
190c0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
190d0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
190e0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
190f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
19100 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
19110 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
19120 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
19130 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
19140 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
19150 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
19160 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
19170 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
19180 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
19190 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
191a0 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
191b0 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
191c0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
191d0 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  on of aggregate 
191e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
191f0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
19200 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20  o allocate.** a 
19210 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74  structure for st
19220 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
19230 65 2e 20 20 54 68 65 20 66 69 72 73 74 20 74 69  e.  The first ti
19240 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  me this routine.
19250 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  ** is called for
19260 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
19270 67 72 65 67 61 74 65 2c 20 61 20 6e 65 77 20 73  gregate, a new s
19280 74 72 75 63 74 75 72 65 20 6f 66 20 73 69 7a 65  tructure of size
19290 20 6e 42 79 74 65 73 0a 2a 2a 20 69 73 20 61 6c   nBytes.** is al
192a0 6c 6f 63 61 74 65 64 2c 20 7a 65 72 6f 65 64 2c  located, zeroed,
192b0 20 61 6e 64 20 72 65 74 75 72 6e 65 64 2e 20 20   and returned.  
192c0 4f 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  On subsequent ca
192d0 6c 6c 73 20 28 66 6f 72 20 74 68 65 0a 2a 2a 20  lls (for the.** 
192e0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 69  same aggregate i
192f0 6e 73 74 61 6e 63 65 29 20 74 68 65 20 73 61 6d  nstance) the sam
19300 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
19310 72 6e 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65  rned.  The imple
19320 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
19330 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61  the aggregate ca
19340 6e 20 75 73 65 20 74 68 65 20 72 65 74 75 72 6e  n use the return
19350 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63  ed buffer to acc
19360 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a  umulate data..**
19370 0a 2a 2a 20 54 68 65 20 62 75 66 66 65 72 20 61  .** The buffer a
19380 6c 6c 6f 63 61 74 65 64 20 69 73 20 66 72 65 65  llocated is free
19390 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
193a0 62 79 20 53 51 4c 69 74 65 20 77 68 61 6e 20 74  by SQLite whan t
193b0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
193c0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
193d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
193e0 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
193f0 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  d be a copy of t
19400 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
19410 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
19420 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
19430 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
19440 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  t.** parameter t
19450 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  o the callback r
19460 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
19470 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
19480 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
19490 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
194a0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
194b0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
194c0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
194d0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
194e0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
194f0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
19500 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
19510 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
19520 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
19530 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
19540 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
19550 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
19560 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
19570 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
19580 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
19590 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
195a0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
195b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
195c0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
195d0 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f  tines.** used to
195e0 20 72 65 67 69 73 74 65 72 20 75 73 65 72 20 66   register user f
195f0 75 6e 63 74 69 6f 6e 73 20 69 73 20 61 76 61 69  unctions is avai
19600 6c 61 62 6c 65 20 74 6f 0a 2a 2a 20 74 68 65 20  lable to.** the 
19610 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
19620 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 75  f the function u
19630 73 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 0a  sing this call..
19640 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
19650 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
19660 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
19670 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
19680 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
19690 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
196a0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
196b0 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
196c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
196d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
196e0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
196f0 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
19700 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66   following two f
19710 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
19720 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53  used by scalar S
19730 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
19740 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
19750 61 2d 64 61 74 61 20 77 69 74 68 20 61 72 67 75  a-data with argu
19760 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
19770 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
19780 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
19790 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
197a0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
197b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
197c0 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
197d0 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
197e0 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
197f0 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
19800 6d 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65  meta-data may be
19810 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
19820 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
19830 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
19840 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
19850 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
19860 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
19870 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
19880 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
19890 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
198a0 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
198b0 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20  as.** meta-data 
198c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
198d0 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
198e0 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
198f0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
19900 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
19910 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
19920 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
19930 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
19940 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
19950 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
19960 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
19970 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
19980 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
19990 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
199a0 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
199b0 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
199c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
199d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
199e0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
199f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
19a00 74 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  to the meta-data
19a10 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
19a20 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
19a30 6d 65 6e 74 20 76 61 6c 75 65 20 74 6f 20 74 68  ment value to th
19a40 65 20 63 75 72 72 65 6e 74 20 53 51 4c 20 66 75  e current SQL fu
19a50 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 2c 20  nction.** call, 
19a60 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
19a70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
19a80 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61   If no meta-data
19a90 20 68 61 73 20 62 65 65 6e 20 73 65 74 20 66 6f   has been set fo
19aa0 72 0a 2a 2a 20 74 68 61 74 20 76 61 6c 75 65 2c  r.** that value,
19ab0 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
19ac0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
19ad0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
19ae0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
19af0 29 20 69 73 20 75 73 65 64 20 74 6f 20 61 73 73  ) is used to ass
19b00 6f 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61  ociate meta-data
19b10 20 77 69 74 68 20 61 6e 20 53 51 4c 0a 2a 2a 20   with an SQL.** 
19b20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
19b30 74 2e 20 54 68 65 20 74 68 69 72 64 20 70 61 72  t. The third par
19b40 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
19b50 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 2d  ter to the meta-
19b60 64 61 74 61 0a 2a 2a 20 74 6f 20 62 65 20 61 73  data.** to be as
19b70 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
19b80 65 20 4e 74 68 20 75 73 65 72 20 66 75 6e 63 74  e Nth user funct
19b90 69 6f 6e 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ion argument val
19ba0 75 65 2e 20 54 68 65 20 66 6f 75 72 74 68 0a 2a  ue. The fourth.*
19bb0 2a 20 70 61 72 61 6d 65 74 65 72 20 73 70 65 63  * parameter spec
19bc0 69 66 69 65 73 20 61 20 64 65 73 74 72 75 63 74  ifies a destruct
19bd0 6f 72 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  or that will be 
19be0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 6d 65  called on the me
19bf0 74 61 2d 0a 2a 2a 20 64 61 74 61 20 70 6f 69 6e  ta-.** data poin
19c00 74 65 72 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ter to release i
19c10 74 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  t when it is no 
19c20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
19c30 20 49 66 20 74 68 65 20 0a 2a 2a 20 64 65 73 74   If the .** dest
19c40 72 75 63 74 6f 72 20 69 73 20 4e 55 4c 4c 2c 20  ructor is NULL, 
19c50 69 74 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  it is not invoke
19c60 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63  d..**.** In prac
19c70 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61 20  tice, meta-data 
19c80 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
19c90 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
19ca0 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
19cb0 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
19cc0 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
19cd0 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
19ce0 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
19cf0 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51  ** values and SQ
19d00 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a  L variables..**.
19d10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
19d20 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
19d30 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
19d40 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
19d50 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
19d60 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
19d70 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
19d80 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
19d90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
19da0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
19db0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
19dc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
19dd0 6e 74 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20  nt, void*, void 
19de0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
19df0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
19e00 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
19e10 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
19e20 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
19e30 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
19e40 65 63 69 61 6c 20 76 61 6c 75 65 20 66 6f 72 20  ecial value for 
19e50 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
19e60 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
19e70 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
19e80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
19e90 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
19ea0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
19eb0 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74  )].  If the dest
19ec0 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
19ed0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
19ee0 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
19ef0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
19f00 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
19f10 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
19f20 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
19f30 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
19f40 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
19f50 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   The .** SQLITE_
19f60 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
19f70 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
19f80 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
19f90 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
19fa0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
19fb0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
19fc0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
19fd0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
19fe0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
19ff0 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
1a000 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
1a010 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
1a020 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
1a030 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
1a040 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
1a050 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
1a060 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
1a070 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
1a080 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
1a090 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
1a0a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
1a0b0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
1a0c0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
1a0d0 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
1a0e0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
1a0f0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
1a100 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
1a110 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a120 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
1a130 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
1a140 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
1a150 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1a160 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
1a170 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
1a180 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
1a190 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
1a1a0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
1a1b0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
1a1c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
1a1d0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
1a1e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
1a1f0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
1a200 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
1a210 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1a220 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
1a230 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
1a240 6c 69 6b 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71  like the .** [sq
1a250 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
1a260 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
1a270 5d 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  ] family of func
1a280 74 69 6f 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f  tions used.** to
1a290 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
1a2a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
1a2b0 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
1a2c0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
1a2d0 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   to the.** [sqli
1a2e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
1a2f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64  sqlite3_bind_* d
1a300 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1a310 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
1a320 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1a330 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
1a340 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
1a350 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1a360 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
1a370 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
1a380 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
1a390 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
1a3a0 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
1a3b0 2e 20 20 54 68 65 0a 2a 2a 20 70 61 72 61 6d 65  .  The.** parame
1a3c0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1a3d0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
1a3e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1a3f0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 69 73 20  error16().** is 
1a400 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
1a410 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1a420 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1a430 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
1a440 63 61 75 73 65 20 74 68 65 20 66 75 6e 63 74 69  cause the functi
1a450 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
1a460 6e 0a 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e  n.** to throw an
1a470 64 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  d error indicati
1a480 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
1a490 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c   or BLOB is to l
1a4a0 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73  ong.** to repres
1a4b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ent..**.** These
1a4c0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
1a4d0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
1a4e0 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 68  thin the same th
1a4f0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
1a500 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f  QL function asso
1a510 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1a520 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
1a530 5d 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 76 6f  ] pointer..*/.vo
1a540 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1a550 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
1a560 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
1a570 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
1a580 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
1a590 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1a5a0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
1a5b0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
1a5c0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1a5d0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
1a5e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
1a5f0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
1a600 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1a610 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
1a620 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
1a630 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
1a640 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1a650 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
1a660 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
1a670 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
1a680 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
1a690 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
1a6a0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
1a6b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
1a6c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1a6d0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
1a6e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
1a6f0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
1a700 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
1a710 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
1a720 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
1a730 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
1a740 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1a750 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
1a760 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
1a770 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
1a780 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
1a790 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1a7a0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
1a7b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
1a7c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
1a7d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
1a7e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1a7f0 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
1a800 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
1a810 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
1a820 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1a830 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
1a840 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
1a850 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
1a860 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
1a870 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1a880 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1a890 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
1a8a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
1a8b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
1a8c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1a8d0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
1a8e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
1a8f0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
1a900 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
1a910 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
1a920 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  nces.**.** These
1a930 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75   functions are u
1a940 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63  sed to add new c
1a950 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
1a960 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71  es to the.** [sq
1a970 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73  lite3*] handle s
1a980 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
1a990 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
1a9a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
1a9b0 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
1a9c0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
1a9d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
1a9e0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
1a9f0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
1aa00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
1aa10 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
1aa20 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
1aa30 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
1aa40 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
1aa50 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1aa60 74 69 6f 6e 31 36 28 29 2e 20 20 49 6e 20 61 6c  tion16().  In al
1aa70 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e  l cases.** the n
1aa80 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73  ame is passed as
1aa90 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
1aaa0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
1aab0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
1aac0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
1aad0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
1aae0 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
1aaf0 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
1ab00 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49  TF16LE] or [SQLI
1ab10 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64  TE_UTF16BE], ind
1ab20 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
1ab30 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a   user-supplied.*
1ab40 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  * routine expect
1ab50 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70  s to be passed p
1ab60 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
1ab70 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  gs encoded using
1ab80 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31   UTF-8,.** UTF-1
1ab90 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  6 little-endian 
1aba0 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
1abb0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
1abc0 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74  y..**.** A point
1abd0 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73  er to the user s
1abe0 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
1abf0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
1ac00 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61  s the fifth.** a
1ac10 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 69  rgument. If it i
1ac20 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20  s NULL, this is 
1ac30 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65  the same as dele
1ac40 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69  ting the collati
1ac50 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28  on.** sequence (
1ac60 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  so that SQLite c
1ac70 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e  annot call it an
1ac80 79 6d 6f 72 65 29 2e 20 45 61 63 68 20 74 69 6d  ymore). Each tim
1ac90 65 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 73 75  e the user.** su
1aca0 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20  pplied function 
1acb0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69  is invoked, it i
1acc0 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20  s passed a copy 
1acd0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73  of the void* pas
1ace0 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 66 6f  sed as.** the fo
1acf0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
1ad00 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1ad10 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a 2a  collation() or.*
1ad20 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
1ad30 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20 61  _collation16() a
1ad40 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61  s its first para
1ad50 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
1ad60 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d   remaining argum
1ad70 65 6e 74 73 20 74 6f 20 74 68 65 20 75 73 65 72  ents to the user
1ad80 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e  -supplied routin
1ad90 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67  e are two string
1ada0 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65  s,.** each repre
1adb0 73 65 6e 74 65 64 20 62 79 20 61 20 5b 6c 65 6e  sented by a [len
1adc0 67 74 68 2c 20 64 61 74 61 5d 20 70 61 69 72 20  gth, data] pair 
1add0 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74  and encoded in t
1ade0 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74  he encoding.** t
1adf0 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61  hat was passed a
1ae00 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
1ae10 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f  ment when the co
1ae20 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1ae30 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72   was.** register
1ae40 65 64 2e 20 54 68 65 20 75 73 65 72 20 72 6f 75  ed. The user rou
1ae50 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75  tine should retu
1ae60 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  rn negative, zer
1ae70 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66  o or positive if
1ae80 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 73 74  .** the first st
1ae90 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
1aea0 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
1aeb0 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
1aec0 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e   second.** strin
1aed0 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31  g. i.e. (STRING1
1aee0 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a   - STRING2)..**.
1aef0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
1af00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
1af10 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
1af20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1af30 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78  ollation().** ex
1af40 63 61 70 74 20 74 68 61 74 20 69 74 20 74 61 6b  capt that it tak
1af50 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75  es an extra argu
1af60 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
1af70 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a  destructor for.*
1af80 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e  * the collation.
1af90 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72    The destructor
1afa0 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   is called when 
1afb0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
1afc0 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e  .** destroyed an
1afd0 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f  d is passed a co
1afe0 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  py of the fourth
1aff0 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a   parameter void*
1b000 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74   pointer.** of t
1b010 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
1b020 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
1b030 2e 20 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72  .  Collations ar
1b040 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e  e destroyed when
1b050 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 6f 76 65  .** they are ove
1b060 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
1b070 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
1b080 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
1b090 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72   functions.** or
1b0a0 20 77 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   when the [sqlit
1b0b0 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61  e3*] database ha
1b0c0 6e 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 75  ndle is closed u
1b0d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
1b0e0 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ose()]..**.** Th
1b0f0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
1b100 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
1b110 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70  interface is exp
1b120 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a  erimental and.**
1b130 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
1b140 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ge in future rel
1b150 65 61 73 65 73 2e 20 20 54 68 65 20 6f 74 68 65  eases.  The othe
1b160 72 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  r collation crea
1b170 74 69 6f 6e 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  tion.** function
1b180 73 20 61 72 65 20 73 74 61 62 6c 65 2e 0a 2a 2f  s are stable..*/
1b190 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
1b1a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20  ate_collation(. 
1b1b0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
1b1c0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
1b1d0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
1b1e0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
1b1f0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
1b200 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
1b210 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
1b220 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
1b230 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1b240 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
1b250 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
1b260 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
1b270 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
1b280 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
1b290 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
1b2a0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
1b2b0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
1b2c0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
1b2d0 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
1b2e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1b2f0 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
1b300 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
1b310 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
1b320 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
1b330 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
1b340 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
1b350 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
1b360 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
1b370 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b380 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
1b390 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
1b3a0 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76  .** To avoid hav
1b3b0 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
1b3c0 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
1b3d0 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
1b3e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
1b3f0 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
1b400 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
1b410 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
1b420 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
1b430 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  ** database hand
1b440 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20  le to be called 
1b450 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
1b460 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
1b470 73 65 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72  sequence is.** r
1b480 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  equired..**.** I
1b490 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
1b4a0 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
1b4b0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
1b4c0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
1b4d0 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
1b4e0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
1b4f0 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
1b500 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
1b510 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
1b520 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
1b530 55 54 46 2d 38 2e 20 49 66 20 73 71 6c 69 74 65  UTF-8. If sqlite
1b540 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
1b550 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 20  ed16() is used, 
1b560 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65  the names.** are
1b570 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
1b580 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
1b590 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20  ive byte order. 
1b5a0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
1b5b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  .** function rep
1b5c0 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69  laces any existi
1b5d0 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ng callback..**.
1b5e0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1b5f0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
1b600 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1b610 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
1b620 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
1b630 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
1b640 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
1b650 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
1b660 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
1b670 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
1b680 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1b690 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
1b6a0 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20  base.** handle. 
1b6b0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
1b6c0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
1b6d0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
1b6e0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
1b6f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
1b700 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
1b710 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
1b720 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
1b730 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
1b740 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
1b750 65 71 75 69 72 65 64 2e 20 54 68 65 20 66 6f 75  equired. The fou
1b760 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
1b770 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1b780 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
1b790 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
1b7a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
1b7b0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
1b7c0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
1b7d0 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
1b7e0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
1b7f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
1b800 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
1b810 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1b820 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
1b830 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
1b840 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
1b850 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1b860 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
1b870 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
1b880 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
1b890 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
1b8a0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
1b8b0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
1b8c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
1b8d0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
1b8e0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
1b8f0 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
1b900 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
1b910 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
1b920 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
1b930 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
1b940 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
1b950 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
1b960 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
1b970 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
1b980 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
1b990 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
1b9a0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
1b9b0 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
1b9c0 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
1b9d0 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
1b9e0 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
1b9f0 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
1ba00 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
1ba10 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1ba20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1ba30 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
1ba40 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
1ba50 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
1ba60 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
1ba70 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
1ba80 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
1ba90 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
1baa0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
1bab0 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
1bac0 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
1bad0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
1bae0 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
1baf0 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
1bb00 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
1bb10 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
1bb20 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
1bb30 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
1bb40 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
1bb50 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
1bb60 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
1bb70 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
1bb80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
1bb90 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
1bba0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1bbb0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1bbc0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
1bbd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1bbe0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
1bbf0 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
1bc00 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
1bc10 20 43 41 50 49 33 52 45 46 3a 20 20 53 75 73 70   CAPI3REF:  Susp
1bc20 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
1bc30 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
1bc40 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
1bc50 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75  on causes the cu
1bc60 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20  rrent thread to 
1bc70 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
1bc80 6e 0a 2a 2a 20 61 20 6e 75 6d 62 65 72 20 6f 66  n.** a number of
1bc90 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
1bca0 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
1bcb0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1bcc0 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
1bcd0 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
1bce0 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
1bcf0 65 71 75 65 73 74 73 20 77 69 74 68 20 0a 2a 2a  equests with .**
1bd00 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
1bd10 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
1bd20 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
1bd30 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
1bd40 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  o .** the neares
1bd50 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
1bd60 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
1bd70 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
1bd80 74 75 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65  tually .** reque
1bd90 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
1bda0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1bdb0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1bdc0 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
1bdd0 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
1bde0 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
1bdf0 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
1be00 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
1be10 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1be20 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74  ] object..*/.int
1be30 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
1be40 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1be50 33 52 45 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54  3REF:  Name Of T
1be60 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
1be70 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
1be80 73 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20  s.**.** If this 
1be90 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
1bea0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1beb0 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
1bec0 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
1bed0 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
1bee0 2e 6b 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  .ka. directory),
1bef0 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
1bf00 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
1bf10 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
1bf20 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e  ill be placed in
1bf30 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
1bf40 20 20 49 66 20 74 68 69 73 20 76 61 72 69 61 62    If this variab
1bf50 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f  le.** is NULL po
1bf60 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
1bf70 74 65 20 64 6f 65 73 20 61 20 73 65 61 72 63 68  te does a search
1bf80 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
1bf90 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  ate temporary.**
1bfa0 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
1bfb0 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65 20 5b 73 71 6c  .**.** Once [sql
1bfc0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 68 61 73  ite3_open()] has
1bfd0 20 62 65 65 6e 20 63 61 6c 6c 65 64 2c 20 63 68   been called, ch
1bfe0 61 6e 67 69 6e 67 20 74 68 69 73 20 76 61 72 69  anging this vari
1bff0 61 62 6c 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76  able will.** inv
1c000 61 6c 69 64 61 74 65 20 74 68 65 20 63 75 72 72  alidate the curr
1c010 65 6e 74 20 74 65 6d 70 6f 72 61 72 79 20 64 61  ent temporary da
1c020 74 61 62 61 73 65 2c 20 69 66 20 61 6e 79 2e 20  tabase, if any. 
1c030 20 47 65 6e 65 72 61 6c 6c 79 20 73 70 65 61 6b   Generally speak
1c040 69 6e 67 2c 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  ing,.** it is no
1c050 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65  t safe to invoke
1c060 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 66   this routine af
1c070 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ter [sqlite3_ope
1c080 6e 28 29 5d 20 68 61 73 0a 2a 2a 20 62 65 65 6e  n()] has.** been
1c090 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 53 51 4c 49   called..*/.SQLI
1c0a0 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
1c0b0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
1c0c0 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
1c0d0 41 50 49 33 52 45 46 3a 20 20 54 65 73 74 20 54  API3REF:  Test T
1c0e0 6f 20 53 65 65 20 49 66 20 54 68 65 20 44 61 74  o See If The Dat
1c0f0 61 62 73 65 20 49 73 20 49 6e 20 41 75 74 6f 2d  abse Is In Auto-
1c100 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 0a 2a  Commit Mode.**.*
1c110 2a 20 54 65 73 74 20 74 6f 20 73 65 65 20 77 68  * Test to see wh
1c120 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1c130 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c140 74 69 6f 6e 20 69 73 20 69 6e 20 61 75 74 6f 63  tion is in autoc
1c150 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f 64 65 2e 20 20  ommit.** mode.  
1c160 52 65 74 75 72 6e 20 54 52 55 45 20 69 66 20 69  Return TRUE if i
1c170 74 20 69 73 20 61 6e 64 20 46 41 4c 53 45 20 69  t is and FALSE i
1c180 66 20 6e 6f 74 2e 20 20 41 75 74 6f 63 6f 6d 6d  f not.  Autocomm
1c190 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a  it mode is on.**
1c1a0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 41 75   by default.  Au
1c1b0 74 6f 63 6f 6d 6d 69 74 20 69 73 20 64 69 73 61  tocommit is disa
1c1c0 62 6c 65 64 20 62 79 20 61 20 42 45 47 49 4e 20  bled by a BEGIN 
1c1d0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 72 65  statement and re
1c1e0 65 6e 61 62 6c 65 64 0a 2a 2a 20 62 79 20 74 68  enabled.** by th
1c1f0 65 20 6e 65 78 74 20 43 4f 4d 4d 49 54 20 6f 72  e next COMMIT or
1c200 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a   ROLLBACK..**.**
1c210 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
1c220 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
1c230 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
1c240 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1c250 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
1c260 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
1c270 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
1c280 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1c290 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
1c2a0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
1c2b0 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
1c2c0 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  it(sqlite3*);../
1c2d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1c2e0 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
1c2f0 65 20 48 61 6e 64 6c 65 20 41 73 73 6f 63 69 61  e Handle Associa
1c300 74 65 64 20 57 69 74 68 20 41 20 50 72 65 70 61  ted With A Prepa
1c310 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
1c320 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 5b  .** Return the [
1c330 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61  sqlite3*] databa
1c340 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 77 68 69  se handle to whi
1c350 63 68 20 61 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ch a.** [sqlite3
1c360 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
1c370 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
1c380 6e 67 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ngs..** This is 
1c390 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
1c3a0 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61  e handle that wa
1c3b0 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61  s.** the first a
1c3c0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
1c3d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c3e0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
1c3f0 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20 77 61  iants.** that wa
1c400 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  s used to create
1c410 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
1c420 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
1c430 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  e..*/.sqlite3 *s
1c440 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
1c450 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
1c460 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
1c470 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
1c480 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
1c490 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
1c4a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1c4b0 65 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 20 63  es.** register c
1c4c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1c4d0 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  s to be invoked 
1c4e0 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
1c4f0 61 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 63 6f 6d  action.** is com
1c500 6d 69 74 74 65 64 20 6f 72 20 72 6f 6c 6c 65 64  mitted or rolled
1c510 20 62 61 63 6b 2e 20 20 54 68 65 20 70 41 72 67   back.  The pArg
1c520 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
1c530 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 74  sed through.** t
1c540 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20  o the callback. 
1c550 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
1c560 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
1c570 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72  k function .** r
1c580 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1c590 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
1c5a0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
1c5b0 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
1c5c0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
1c5d0 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
1c5e0 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
1c5f0 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c  ed, its pArg val
1c600 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ue is returned..
1c610 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  ** Otherwise NUL
1c620 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
1c630 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67  *.** Registering
1c640 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
1c650 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
1c660 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f  llback..**.** Fo
1c670 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
1c680 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72  f this API, a tr
1c690 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69  ansaction is sai
1c6a0 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 20 0a  d to have been .
1c6b0 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69  ** rolled back i
1c6c0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52  f an explicit "R
1c6d0 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65  OLLBACK" stateme
1c6e0 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20  nt is executed, 
1c6f0 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f  or.** an error o
1c700 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75  r constraint cau
1c710 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20  ses an implicit 
1c720 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75  rollback to occu
1c730 72 2e 20 54 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  r. The .** callb
1c740 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
1c750 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
1c760 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
1c770 61 6c 6c 79 20 72 6f 6c 6c 65 64 0a 2a 2a 20 62  ally rolled.** b
1c780 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
1c790 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c7a0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
1c7b0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 65  *.** These are e
1c7c0 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
1c7d0 72 66 61 63 65 73 20 61 6e 64 20 61 72 65 20 73  rfaces and are s
1c7e0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1c7f0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1c800 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
1c810 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
1c820 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
1c830 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
1c840 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
1c850 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
1c860 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
1c870 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c880 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
1c890 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
1c8a0 6b 73 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  ks.**.** Registe
1c8b0 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
1c8c0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 64  ction with the d
1c8d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c8e0 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  on identified by
1c8f0 20 74 68 65 20 0a 2a 2a 20 66 69 72 73 74 20 61   the .** first a
1c900 72 67 75 6d 65 6e 74 20 74 6f 20 62 65 20 69 6e  rgument to be in
1c910 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
1c920 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
1c930 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
1c940 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  eted..** Any cal
1c950 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
1c960 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
1c970 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 66 6f  this function fo
1c980 72 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 64  r the same .** d
1c990 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c9a0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
1c9b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
1c9c0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
1c9d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1c9e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
1c9f0 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20 72 6f  ke when a .** ro
1ca00 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
1ca10 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
1ca20 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
1ca30 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c  ument to the cal
1ca40 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 61 20 63 6f  lback is.** a co
1ca50 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  py of the third 
1ca60 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1ca70 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
1ca80 29 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61  ). The second ca
1ca90 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75 6d  llback .** argum
1caa0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 53 51  ent is one of SQ
1cab0 4c 49 54 45 5f 49 4e 53 45 52 54 2c 20 53 51 4c  LITE_INSERT, SQL
1cac0 49 54 45 5f 44 45 4c 45 54 45 20 6f 72 20 53 51  ITE_DELETE or SQ
1cad0 4c 49 54 45 5f 55 50 44 41 54 45 2c 20 64 65 70  LITE_UPDATE, dep
1cae0 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 74 68 65  ending.** on the
1caf0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1cb00 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
1cb10 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ack to be invoke
1cb20 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  d. The third and
1cb30 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75   .** fourth argu
1cb40 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
1cb50 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
1cb60 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 64 61  inters to the da
1cb70 74 61 62 61 73 65 20 61 6e 64 20 0a 2a 2a 20 74  tabase and .** t
1cb80 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69  able name contai
1cb90 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65  ning the affecte
1cba0 64 20 72 6f 77 2e 20 54 68 65 20 66 69 6e 61 6c  d row. The final
1cbb0 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
1cbc0 74 65 72 20 69 73 20 0a 2a 2a 20 74 68 65 20 72  ter is .** the r
1cbd0 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 2e  owid of the row.
1cbe0 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   In the case of 
1cbf0 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
1cc00 69 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74  is the rowid aft
1cc10 65 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61 74  er .** the updat
1cc20 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
1cc30 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
1cc40 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
1cc50 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
1cc60 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
1cc70 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
1cc80 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
1cc90 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
1cca0 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20  equence)..**.** 
1ccb0 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
1ccc0 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
1ccd0 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
1cce0 74 73 20 70 41 72 67 20 76 61 6c 75 65 20 69 73  ts pArg value is
1ccf0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74   returned..** Ot
1cd00 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
1cd10 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 76 6f 69  returned..*/.voi
1cd20 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74  d *sqlite3_updat
1cd30 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65  e_hook(.  sqlite
1cd40 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  3*, .  void(*)(v
1cd50 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20  oid *,int ,char 
1cd60 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e  const *,char con
1cd70 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  st *,sqlite3_int
1cd80 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a  64),.  void*.);.
1cd90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cda0 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61    Enable Or Disa
1cdb0 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
1cdc0 20 43 61 63 68 65 0a 2a 2a 0a 2a 2a 20 54 68 69   Cache.**.** Thi
1cdd0 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  s routine enable
1cde0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
1cdf0 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65  e sharing of the
1ce00 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a   database cache.
1ce10 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61  ** and schema da
1ce20 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65  ta structures be
1ce30 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e  tween connection
1ce40 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  s to the same da
1ce50 74 61 62 61 73 65 2e 0a 2a 2a 20 53 68 61 72 69  tabase..** Shari
1ce60 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  ng is enabled if
1ce70 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
1ce80 20 74 72 75 65 20 61 6e 64 20 64 69 73 61 62 6c   true and disabl
1ce90 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
1cea0 6e 74 0a 2a 2a 20 69 73 20 66 61 6c 73 65 2e 0a  nt.** is false..
1ceb0 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20  **.** Beginning 
1cec0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
1ced0 6e 20 33 2e 35 2e 30 2c 20 63 61 63 68 65 20 73  n 3.5.0, cache s
1cee0 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
1cef0 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 0a 2a  d and disabled.*
1cf00 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20  * for an entire 
1cf10 70 72 6f 63 65 73 73 2e 20 20 49 6e 20 70 72 69  process.  In pri
1cf20 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  or versions of S
1cf30 51 4c 69 74 65 2c 20 73 68 61 72 69 6e 67 20 77  QLite, sharing w
1cf40 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72  as.** enabled or
1cf50 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61   disabled for ea
1cf60 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61  ch thread separa
1cf70 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tely..**.** The 
1cf80 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
1cf90 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
1cfa0 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
1cfb0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
1cfc0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
1cfd0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1cfe0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1cff0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1d000 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78  open16()]..** Ex
1d010 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  isting database 
1d020 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74  connections cont
1d030 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61  inue use the sha
1d040 72 69 6e 67 20 6d 6f 64 65 20 74 68 61 74 20 77  ring mode that w
1d050 61 73 0a 2a 2a 20 69 6e 20 65 66 66 65 63 74 20  as.** in effect 
1d060 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79  at the time they
1d070 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a   were opened..**
1d080 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
1d090 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65  es cannot be use
1d0a0 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20  d with a shared 
1d0b0 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61  cache.  When sha
1d0c0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
1d0d0 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 73 71 6c  enabled, the sql
1d0e0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
1d0f0 6c 65 28 29 20 41 50 49 20 75 73 65 64 20 74 6f  le() API used to
1d100 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72   register.** vir
1d110 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c  tual tables will
1d120 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61   always return a
1d130 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  n error..**.** T
1d140 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
1d150 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
1d160 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
1d170 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f  was.** enabled o
1d180 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65  r disabled succe
1d190 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 53 51  ssfully.  An [SQ
1d1a0 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72  LITE_ERROR | err
1d1b0 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72  or code].** is r
1d1c0 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
1d1d0 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20  e..**.** Shared 
1d1e0 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65  cache is disable
1d1f0 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
1d200 20 62 61 63 6b 77 61 72 64 20 63 6f 6d 70 61 74   backward compat
1d210 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
1d220 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
1d230 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29  hared_cache(int)
1d240 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d250 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f 20 46  F:  Attempt To F
1d260 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a  ree Heap Memory.
1d270 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74 6f  **.** Attempt to
1d280 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66   free N bytes of
1d290 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
1d2a0 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
1d2b0 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 6d 65  -essential.** me
1d2c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1d2d0 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
1d2e0 61 62 61 73 65 20 6c 69 62 72 61 72 79 20 28 65  abase library (e
1d2f0 78 61 6d 70 6c 65 3a 20 6d 65 6d 6f 72 79 20 0a  xample: memory .
1d300 2a 2a 20 75 73 65 64 20 74 6f 20 63 61 63 68 65  ** used to cache
1d310 20 64 61 74 61 62 61 73 65 20 70 61 67 65 73 20   database pages 
1d320 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  to improve perfo
1d330 72 6d 61 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 54  rmance)..**.** T
1d340 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
1d350 6e 6f 74 20 61 20 70 61 72 74 20 6f 66 20 73 74  not a part of st
1d360 61 6e 64 61 72 64 20 62 75 69 6c 64 73 2e 20 20  andard builds.  
1d370 49 74 20 69 73 20 6f 6e 6c 79 20 63 72 65 61 74  It is only creat
1d380 65 64 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  ed.** if SQLite 
1d390 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
1d3a0 20 74 68 65 20 53 51 4c 49 54 45 5f 45 4e 41 42   the SQLITE_ENAB
1d3b0 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
1d3c0 4d 45 4e 54 20 6d 61 63 72 6f 2e 0a 2a 2f 0a 69  MENT macro..*/.i
1d3d0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  nt sqlite3_relea
1d3e0 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a  se_memory(int);.
1d3f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d400 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74    Impose A Limit
1d410 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a   On Heap Size.**
1d420 0a 2a 2a 20 50 6c 61 63 65 20 61 20 22 73 6f 66  .** Place a "sof
1d430 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  t" limit on the 
1d440 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
1d450 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
1d460 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62  e allocated.** b
1d470 79 20 53 51 4c 69 74 65 2e 20 20 49 66 20 61 6e  y SQLite.  If an
1d480 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61   internal alloca
1d490 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
1d4a0 64 20 0a 2a 2a 20 74 68 61 74 20 77 6f 75 6c 64  d .** that would
1d4b0 20 65 78 63 65 65 64 20 74 68 65 20 73 70 65 63   exceed the spec
1d4c0 69 66 69 65 64 20 6c 69 6d 69 74 2c 20 5b 73 71  ified limit, [sq
1d4d0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
1d4e0 6d 6f 72 79 28 29 5d 20 69 73 0a 2a 2a 20 69 6e  mory()] is.** in
1d4f0 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  voked one or mor
1d500 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20  e times to free 
1d510 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65  up some space be
1d520 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  fore the allocat
1d530 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61 64 65 2e 0a  ion.** is made..
1d540 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20  **.** The limit 
1d550 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22  is called "soft"
1d560 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71  , because if [sq
1d570 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
1d580 6d 6f 72 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a  mory()] cannot.*
1d590 2a 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e  * free sufficien
1d5a0 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76  t memory to prev
1d5b0 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72  ent the limit fr
1d5c0 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65  om being exceede
1d5d0 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  d,.** the memory
1d5e0 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e   is allocated an
1d5f0 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72  yway and the cur
1d600 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70  rent operation p
1d610 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41  roceeds..**.** A
1d620 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
1d630 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65  o value for N me
1d640 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69  ans that there i
1d650 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c  s no soft heap l
1d660 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  imit and.** [sql
1d670 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
1d680 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79  ory()] will only
1d690 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
1d6a0 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73  memory is exhaus
1d6b0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  ted..** The defa
1d6c0 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
1d6d0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
1d6e0 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t is zero..**.**
1d6f0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
1d700 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68  best effort to h
1d710 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65  onor the soft he
1d720 61 70 20 6c 69 6d 69 74 2e 20 20 42 75 74 20 69  ap limit.  But i
1d730 66 20 69 74 0a 2a 2a 20 69 73 20 75 6e 61 62 6c  f it.** is unabl
1d740 65 20 74 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f  e to reduce memo
1d750 72 79 20 75 73 61 67 65 20 62 65 6c 6f 77 20 74  ry usage below t
1d760 68 65 20 73 6f 66 74 20 6c 69 6d 69 74 2c 20 65  he soft limit, e
1d770 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  xecution will.**
1d780 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75   continue withou
1d790 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66  t error or notif
1d7a0 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69  ication.  This i
1d7b0 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20  s why the limit 
1d7c0 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20  is .** called a 
1d7d0 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49  "soft" limit.  I
1d7e0 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e  t is advisory on
1d7f0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 6f  ly..**.** The so
1d800 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
1d810 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 75 73 69   implemented usi
1d820 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1d830 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 0a  memory_alarm()].
1d840 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 4f  ** interface.  O
1d850 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 6d 65 6d  nly a single mem
1d860 6f 72 79 20 61 6c 61 72 6d 20 69 73 20 61 76 61  ory alarm is ava
1d870 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 64 65  ilable in the de
1d880 66 61 75 6c 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65  fault.** impleme
1d890 6e 74 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 6d  ntation.  This m
1d8a0 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
1d8b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 61 6c 73   application als
1d8c0 6f 20 75 73 65 73 20 74 68 65 0a 2a 2a 20 6d 65  o uses the.** me
1d8d0 6d 6f 72 79 20 61 6c 61 72 6d 20 69 6e 74 65 72  mory alarm inter
1d8e0 66 61 63 65 20 69 74 20 77 69 6c 6c 20 69 6e 74  face it will int
1d8f0 65 72 66 65 72 65 20 77 69 74 68 20 74 68 65 20  erfere with the 
1d900 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
1d910 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c 69  .** soft heap li
1d920 6d 69 74 20 61 6e 64 20 75 6e 64 65 66 69 6e 65  mit and undefine
1d930 64 20 62 65 68 61 76 69 6f 72 20 77 69 6c 6c 20  d behavior will 
1d940 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  result.  .**.** 
1d950 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20  Prior to SQLite 
1d960 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74  version 3.5.0, t
1d970 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
1d980 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65   constrained the
1d990 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
1d9a0 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  ated by a single
1d9b0 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61   thread - the sa
1d9c0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
1d9d0 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  ch this routine.
1d9e0 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e  ** runs.  Beginn
1d9f0 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20  ing with SQLite 
1da00 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74  version 3.5.0, t
1da10 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
1da20 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64  it is.** applied
1da30 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e   to all threads.
1da40 20 20 54 68 65 20 76 61 6c 75 65 20 73 70 65 63    The value spec
1da50 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f  ified for the so
1da60 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a  ft heap limit.**
1da70 20 69 73 20 61 6e 20 62 6f 75 6e 64 20 6f 6e 20   is an bound on 
1da80 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79  the total memory
1da90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
1daa0 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 20 49 6e  all threads.  In
1dab0 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
1dac0 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
1dad0 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
1dae0 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
1daf0 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
1db00 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
1db10 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
1db20 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
1db30 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1db40 33 52 45 46 3a 20 20 45 78 74 72 61 63 74 20 4d  3REF:  Extract M
1db50 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
1db60 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
1db70 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  e.**.** This rou
1db80 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tine.** returns 
1db90 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74 20  meta-data about 
1dba0 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d  a specific colum
1dbb0 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 20  n of a specific 
1dbc0 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
1dbd0 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69  e accessible usi
1dbe0 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ng the connectio
1dbf0 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64 20  n handle passed 
1dc00 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e  as the first fun
1dc10 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65  ction .** argume
1dc20 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  nt..**.** The co
1dc30 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69  lumn is identifi
1dc40 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1dc50 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  , third and four
1dc60 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1dc70 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69   .** this functi
1dc80 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  on. The second p
1dc90 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68  arameter is eith
1dca0 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  er the name of t
1dcb0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28  he database.** (
1dcc0 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65  i.e. "main", "te
1dcd0 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68  mp" or an attach
1dce0 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
1dcf0 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
1dd00 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
1dd10 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73  r NULL. If it is
1dd20 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20   NULL, then all 
1dd30 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
1dd40 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a  es are searched.
1dd50 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65  ** for the table
1dd60 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
1dd70 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68 65  algorithm as the
1dd80 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
1dd90 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73   uses to .** res
1dda0 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
1ddb0 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
1ddc0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  s..**.** The thi
1ddd0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
1dde0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
1ddf0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68   function are th
1de00 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  e table and colu
1de10 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  mn .** name of t
1de20 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
1de30 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
1de40 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
1de50 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a  e parameters .**
1de60 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
1de70 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61  .** Meta informa
1de80 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  tion is returned
1de90 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
1dea0 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
1deb0 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a  ons passed as.**
1dec0 20 74 68 65 20 35 74 68 20 61 6e 64 20 73 75 62   the 5th and sub
1ded0 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
1dee0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
1def0 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73  ion. Any of thes
1df00 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  e .** arguments 
1df10 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20  may be NULL, in 
1df20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
1df30 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
1df40 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a  ment of meta .**
1df50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1df60 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommitted..**.** 
1df70 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74  <pre>.** Paramet
1df80 65 72 20 20 20 20 20 4f 75 74 70 75 74 20 54 79  er     Output Ty
1df90 70 65 20 20 20 20 20 20 44 65 73 63 72 69 70 74  pe      Descript
1dfa0 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d  ion.** ---------
1dfb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1dfc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a  ----------.**.**
1dfd0 20 20 20 35 74 68 20 20 20 20 20 20 20 20 20 63     5th         c
1dfe0 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20  onst char*      
1dff0 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 36  Data type.**   6
1e000 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  th         const
1e010 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61 6d 65   char*      Name
1e020 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
1e030 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1e040 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 20  ce .**   7th    
1e050 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20       int        
1e060 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68        True if th
1e070 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  e column has a N
1e080 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
1e090 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 20  nt.**   8th     
1e0a0 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
1e0b0 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
1e0c0 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
1e0d0 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
1e0e0 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 20  EY.**   9th     
1e0f0 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
1e100 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
1e110 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49   column is AUTOI
1e120 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72  NCREMENT.** </pr
1e130 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20  e>.**.**.** The 
1e140 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74  memory pointed t
1e150 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74  o by the charact
1e160 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  er pointers retu
1e170 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a  rned for the .**
1e180 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
1e190 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
1e1a0 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
1e1b0 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
1e1c0 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74   next .** call t
1e1d0 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41 50 49  o any sqlite API
1e1e0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
1e1f0 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
1e200 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
1e210 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68 65 6e  lly a view, then
1e220 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1e230 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  urned..**.** If 
1e240 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
1e250 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
1e260 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
1e270 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49  d_" and an .** I
1e280 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
1e290 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  EY column has be
1e2a0 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
1e2b0 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
1e2c0 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 61   output .** para
1e2d0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
1e2e0 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
1e2f0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
1e300 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  n. If there is n
1e310 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20  o.** explicitly 
1e320 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c  declared IPK col
1e330 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
1e340 74 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20  tput parameters 
1e350 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 66  are set as .** f
1e360 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ollows:.**.** <p
1e370 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20  re>.**     data 
1e380 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a  type: "INTEGER".
1e390 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e  **     collation
1e3a0 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41   sequence: "BINA
1e3b0 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e  RY".**     not n
1e3c0 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72  ull: 0.**     pr
1e3d0 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20  imary key: 1.** 
1e3e0 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65      auto increme
1e3f0 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a  nt: 0.** </pre>.
1e400 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
1e410 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65  ion may load one
1e420 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73   or more schemas
1e430 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66   from database f
1e440 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65  iles. If an.** e
1e450 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
1e460 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c  ng this process,
1e470 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65   or if the reque
1e480 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f  sted table or co
1e490 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  lumn.** cannot b
1e4a0 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49  e found, an SQLI
1e4b0 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  TE error code is
1e4c0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e   returned and an
1e4d0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
1e4e0 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20 64 61  * left in the da
1e4f0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 28 74  tabase handle (t
1e500 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
1e510 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
1e520 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  msg())..**.** Th
1e530 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
1e540 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
1e550 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
1e560 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
1e570 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
1e580 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70  OLUMN_METADATA p
1e590 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
1e5a0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
1e5b0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
1e5c0 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
1e5d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1e5e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e5f0 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
1e600 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1e610 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
1e620 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1e630 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
1e640 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1e650 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
1e660 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
1e670 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1e680 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
1e690 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
1e6a0 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
1e6b0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
1e6c0 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
1e6d0 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
1e6e0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
1e6f0 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
1e700 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
1e710 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
1e720 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
1e730 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
1e740 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
1e750 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
1e760 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
1e770 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
1e780 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
1e790 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
1e7a0 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
1e7b0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
1e7c0 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
1e7d0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
1e7e0 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 73  : True if colums
1e7f0 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
1e800 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
1e810 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
1e820 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a  n Extension.**.*
1e830 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 6c 6f 61  * Attempt to loa
1e840 64 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65  d an SQLite exte
1e850 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f  nsion library co
1e860 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66  ntained in the f
1e870 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20 20 54  ile.** zFile.  T
1e880 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69  he entry point i
1e890 73 20 7a 50 72 6f 63 2e 20 20 7a 50 72 6f 63 20  s zProc.  zProc 
1e8a0 6d 61 79 20 62 65 20 30 20 69 6e 20 77 68 69 63  may be 0 in whic
1e8b0 68 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 6e 61  h case the.** na
1e8c0 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20  me of the entry 
1e8d0 70 6f 69 6e 74 20 64 65 66 61 75 6c 74 73 20 74  point defaults t
1e8e0 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
1e8f0 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a  sion_init"..**.*
1e900 2a 20 52 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * Return [SQLITE
1e910 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
1e920 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  and [SQLITE_ERRO
1e930 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20  R] if something 
1e940 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a  goes wrong..**.*
1e950 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  * If an error oc
1e960 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73  curs and pzErrMs
1e970 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e  g is not 0, then
1e980 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20   fill *pzErrMsg 
1e990 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d  with .** error m
1e9a0 65 73 73 61 67 65 20 74 65 78 74 2e 20 20 54 68  essage text.  Th
1e9b0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
1e9c0 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74  on should free t
1e9d0 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a 20 62 79  his memory.** by
1e9e0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1e9f0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
1ea00 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   Extension loadi
1ea10 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c  ng must be enabl
1ea20 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1ea30 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
1ea40 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72  tension()].** pr
1ea50 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74  ior to calling t
1ea60 68 69 73 20 41 50 49 20 6f 72 20 61 6e 20 65 72  his API or an er
1ea70 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75  ror will be retu
1ea80 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rned..*/.int sql
1ea90 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
1eaa0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
1eab0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1eac0 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69  Load the extensi
1ead0 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74  on into this dat
1eae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1eaf0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1eb00 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e   *zFile,    /* N
1eb10 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65  ame of the share
1eb20 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  d library contai
1eb30 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a  ning extension *
1eb40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1eb50 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74  zProc,    /* Ent
1eb60 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76  ry point.  Deriv
1eb70 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66  ed from zFile if
1eb80 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70   0 */.  char **p
1eb90 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a  zErrMsg       /*
1eba0 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61   Put error messa
1ebb0 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30  ge here if not 0
1ebc0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1ebd0 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20  PI3REF:  Enable 
1ebe0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
1ebf0 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a  sion Loading.**.
1ec00 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20  ** So as not to 
1ec10 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f  open security ho
1ec20 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70  les in older app
1ec30 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61  lications that a
1ec40 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64  re.** unprepared
1ec50 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78   to deal with ex
1ec60 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c  tension loading,
1ec70 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20   and as a means 
1ec80 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20  of disabling.** 
1ec90 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
1eca0 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  g while evaluati
1ecb0 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ng user-entered 
1ecc0 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  SQL, the followi
1ecd0 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 72 6f  ng.** API is pro
1ece0 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68  vided to turn th
1ecf0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
1ed00 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63  extension()] mec
1ed10 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a  hanism on and.**
1ed20 20 6f 66 66 2e 20 20 49 74 20 69 73 20 6f 66 66   off.  It is off
1ed30 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
1ed40 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a  e ticket #1863..
1ed50 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 68 69 73 20  **.** Call this 
1ed60 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f  routine with ono
1ed70 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20 65 78  ff==1 to turn ex
1ed80 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
1ed90 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c 20 69  on.** and call i
1eda0 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20  t with onoff==0 
1edb0 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63 6b 20  to turn it back 
1edc0 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e  off again..*/.in
1edd0 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
1ede0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
1edf0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74  sqlite3 *db, int
1ee00 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
1ee10 43 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41  CAPI3REF: Make A
1ee20 72 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41  rrangements To A
1ee30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61  utomatically Loa
1ee40 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a  d An Extension.*
1ee50 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 20 61 6e  *.** Register an
1ee60 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79   extension entry
1ee70 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 20 61   point that is a
1ee80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
1ee90 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65 72  oked.** whenever
1eea0 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20   a new database 
1eeb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
1eec0 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ened using.** [s
1eed0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1eee0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1eef0 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
1ef00 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
1ef10 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e 20 62  * This API can b
1ef20 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f  e invoked at pro
1ef30 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20  gram startup in 
1ef40 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65  order to registe
1ef50 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
1ef60 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b   statically link
1ef70 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68  ed extensions th
1ef80 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c  at will be avail
1ef90 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e  able.** to all n
1efa0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1efb0 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 44  ections..**.** D
1efc0 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69  uplicate extensi
1efd0 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ons are detected
1efe0 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   so calling this
1eff0 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69 70 6c   routine multipl
1f000 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
1f010 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69  the same extensi
1f020 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a  on is harmless..
1f030 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
1f040 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e  ne stores a poin
1f050 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e  ter to the exten
1f060 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79  sion in an array
1f070 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f 62 74 61  .** that is obta
1f080 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63  ined from malloc
1f090 28 29 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20  ().  If you run 
1f0a0 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a  a memory leak.**
1f0b0 20 63 68 65 63 6b 65 72 20 6f 6e 20 79 6f 75 72   checker on your
1f0c0 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20   program and it 
1f0d0 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62  reports a leak b
1f0e0 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a  ecause of this.*
1f0f0 2a 20 61 72 72 61 79 2c 20 74 68 65 6e 20 69 6e  * array, then in
1f100 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 61 75  voke [sqlite3_au
1f110 74 6f 6d 61 74 69 63 5f 65 78 74 65 6e 73 69 6f  tomatic_extensio
1f120 6e 5f 72 65 73 65 74 28 29 5d 20 70 72 69 6f 72  n_reset()] prior
1f130 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77 6e 20  .** to shutdown 
1f140 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f  to free the memo
1f150 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 75 74 6f 6d 61  ry..**.** Automa
1f160 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  tic extensions a
1f170 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  pply across all 
1f180 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  threads..**.** T
1f190 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1f1a0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1f1b0 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
1f1c0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d  change or.** rem
1f1d0 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72  oval in future r
1f1e0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
1f1f0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1f200 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
1f210 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f 69  (void *xEntryPoi
1f220 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  nt);.../*.** CAP
1f230 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74  I3REF: Reset Aut
1f240 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e  omatic Extension
1f250 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 44   Loading.**.** D
1f260 69 73 61 62 6c 65 20 61 6c 6c 20 70 72 65 76 69  isable all previ
1f270 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
1f280 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e   automatic exten
1f290 73 69 6f 6e 73 2e 20 20 54 68 69 73 0a 2a 2a 20  sions.  This.** 
1f2a0 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
1f2b0 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c  he effect of all
1f2c0 20 70 72 69 6f 72 20 5b 73 71 6c 69 74 65 33 5f   prior [sqlite3_
1f2d0 61 75 74 6f 6d 61 74 69 63 5f 65 78 74 65 6e 73  automatic_extens
1f2e0 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e  ion()].** calls.
1f2f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 63 61 6c 6c  .**.** This call
1f300 20 64 69 73 61 62 6c 65 64 20 61 75 74 6f 6d 61   disabled automa
1f310 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
1f320 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a  n all threads..*
1f330 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
1f340 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e  ace is experimen
1f350 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65  tal and is subje
1f360 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a  ct to change or.
1f370 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75  ** removal in fu
1f380 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
1f390 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64   SQLite..*/.void
1f3a0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61   sqlite3_reset_a
1f3b0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
1f3c0 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a  id);.../*.******
1f3d0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20   EXPERIMENTAL - 
1f3e0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1f3f0 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
1f400 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a   **************.
1f410 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66  **.** The interf
1f420 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75  ace to the virtu
1f430 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
1f440 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  sm is currently 
1f450 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f  considered.** to
1f460 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   be experimental
1f470 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
1f480 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
1f490 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61   incompatible wa
1f4a0 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69  ys..** If this i
1f4b0 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20  s a problem for 
1f4c0 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20  you, do not use 
1f4d0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74  the interface at
1f4e0 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a   this time..**.*
1f4f0 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75  * When the virtu
1f500 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
1f510 73 6d 20 73 74 61 62 6c 69 7a 65 73 2c 20 77 65  sm stablizes, we
1f520 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
1f530 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
1f540 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
1f550 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
1f560 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
1f570 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a  omment..*/../*.*
1f580 2a 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65  * Structures use
1f590 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c  d by the virtual
1f5a0 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65   table interface
1f5b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1f5c0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
1f5d0 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79  sqlite3_vtab;.ty
1f5e0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1f5f0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20  ite3_index_info 
1f600 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
1f610 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  fo;.typedef stru
1f620 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
1f630 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76  cursor sqlite3_v
1f640 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65  tab_cursor;.type
1f650 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1f660 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65  e3_module sqlite
1f670 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a  3_module;../*.**
1f680 20 41 20 6d 6f 64 75 6c 65 20 69 73 20 61 20 63   A module is a c
1f690 6c 61 73 73 20 6f 66 20 76 69 72 74 75 61 6c 20  lass of virtual 
1f6a0 74 61 62 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f  tables.  Each mo
1f6b0 64 75 6c 65 20 69 73 20 64 65 66 69 6e 65 64 0a  dule is defined.
1f6c0 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74 61 6e 63  ** by an instanc
1f6d0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
1f6e0 6e 67 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  ng structure.  T
1f6f0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63 6f  his structure co
1f700 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79  nsists.** mostly
1f710 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20   of methods for 
1f720 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73  the module..*/.s
1f730 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
1f740 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65  dule {.  int iVe
1f750 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
1f760 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a  Create)(sqlite3*
1f770 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
1f780 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
1f790 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
1f7a0 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
1f7b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
1f7c0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
1f7d0 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
1f7e0 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28  int (*xConnect)(
1f7f0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
1f800 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
1f810 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
1f820 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
1f830 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
1f840 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
1f850 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
1f860 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  r**);.  int (*xB
1f870 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65  estIndex)(sqlite
1f880 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
1f890 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
1f8a0 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69  o*);.  int (*xDi
1f8b0 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  sconnect)(sqlite
1f8c0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
1f8d0 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79    int (*xDestroy
1f8e0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
1f8f0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
1f900 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
1f910 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69  tab *pVTab, sqli
1f920 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
1f930 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69  **ppCursor);.  i
1f940 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
1f950 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
1f960 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  *);.  int (*xFil
1f970 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ter)(sqlite3_vta
1f980 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69  b_cursor*, int i
1f990 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61  dxNum, const cha
1f9a0 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20  r *idxStr,.     
1f9b0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
1f9c0 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  rgc, sqlite3_val
1f9d0 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e  ue **argv);.  in
1f9e0 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74  t (*xNext)(sqlit
1f9f0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
1fa00 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28  ;.  int (*xEof)(
1fa10 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
1fa20 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
1fa30 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f  Column)(sqlite3_
1fa40 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
1fa50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1fa60 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  int);.  int (*xR
1fa70 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74  owid)(sqlite3_vt
1fa80 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
1fa90 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69  te3_int64 *pRowi
1faa0 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64  d);.  int (*xUpd
1fab0 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ate)(sqlite3_vta
1fac0 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  b *, int, sqlite
1fad0 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69  3_value **, sqli
1fae0 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20  te3_int64 *);.  
1faf0 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71  int (*xBegin)(sq
1fb00 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
1fb10 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  b);.  int (*xSyn
1fb20 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  c)(sqlite3_vtab 
1fb30 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
1fb40 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65  *xCommit)(sqlite
1fb50 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
1fb60 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63    int (*xRollbac
1fb70 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  k)(sqlite3_vtab 
1fb80 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
1fb90 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28  *xFindFunction)(
1fba0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
1fbb0 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63  tab, int nArg, c
1fbc0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
1fbd0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
1fbe0 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a           void (*
1fbf0 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  *pxFunc)(sqlite3
1fc00 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
1fc10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
1fc20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1fc30 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70         void **pp
1fc40 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20 28 2a 78  Arg);..  int (*x
1fc50 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  Rename)(sqlite3_
1fc60 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e  vtab *pVtab, con
1fc70 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a  st char *zNew);.
1fc80 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 73 71  };../*.** The sq
1fc90 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
1fca0 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 69   structure and i
1fcb0 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65 73  ts substructures
1fcc0 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70   is used to.** p
1fcd0 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ass information 
1fce0 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65  into and receive
1fcf0 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20   the reply from 
1fd00 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 0a 2a  the xBestIndex.*
1fd10 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 73  * method of an s
1fd20 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 20 20  qlite3_module.  
1fd30 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72  The fields under
1fd40 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20   **Inputs** are 
1fd50 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f  the.** inputs to
1fd60 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
1fd70 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20  are read-only.  
1fd80 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72  xBestIndex inser
1fd90 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74  ts its.** result
1fda0 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74  s into the **Out
1fdb0 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a  puts** fields..*
1fdc0 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72  *.** The aConstr
1fdd0 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63  aint[] array rec
1fde0 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73  ords WHERE claus
1fdf0 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66  e constraints of
1fe00 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a   the.** form:.**
1fe10 0a 2a 2a 20 20 20 20 20 20 20 20 20 63 6f 6c 75  .**         colu
1fe20 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a 0a 2a 2a  mn OP expr.**.**
1fe30 20 57 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20   Where OP is =, 
1fe40 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f 72 20 3e 3d 2e  <, <=, >, or >=.
1fe50 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 72    The particular
1fe60 20 6f 70 65 72 61 74 6f 72 20 69 73 20 73 74 6f   operator is sto
1fe70 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f 6e 73 74  red.** in aConst
1fe80 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65  raint[].op.  The
1fe90 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
1fea0 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69  lumn is stored i
1feb0 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e  n .** aConstrain
1fec0 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43  t[].iColumn.  aC
1fed0 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62  onstraint[].usab
1fee0 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68  le is TRUE if th
1fef0 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65  e.** expr on the
1ff00 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
1ff10 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65   can be evaluate
1ff20 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20  d (and thus the 
1ff30 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73  constraint.** is
1ff40 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c   usable) and fal
1ff50 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e  se if it cannot.
1ff60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d  .**.** The optim
1ff70 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
1ff80 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
1ff90 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
1ffa0 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
1ffb0 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
1ffc0 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6e 6f 73   simplificatinos
1ffd0 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
1ffe0 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
1fff0 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
20000 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
20010 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
20020 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
20030 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
20040 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  * The aConstrain
20050 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72  t[] array only r
20060 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61  eports WHERE cla
20070 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65  use terms in the
20080 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d   correct.** form
20090 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74   that refer to t
200a0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69  he particular vi
200b0 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e  rtual table bein
200c0 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a  g queried..**.**
200d0 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   Information abo
200e0 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  ut the ORDER BY 
200f0 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64  clause is stored
20100 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a   in aOrderBy[]..
20110 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20  ** Each term of 
20120 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73  aOrderBy records
20130 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65   a column of the
20140 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
20150 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73  ..**.** The xBes
20160 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 75  tIndex method mu
20170 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61  st fill aConstra
20180 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20  intUsage[] with 
20190 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
201a0 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65  bout what parame
201b0 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20  ters to pass to 
201c0 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67  xFilter.  If arg
201d0 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a  vIndex>0 then.**
201e0 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
201f0 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72  side of the corr
20200 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74  esponding aConst
20210 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75  raint[] is evalu
20220 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f  ated.** and beco
20230 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65  mes the argvInde
20240 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72  x-th entry in ar
20250 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61  gv.  If aConstra
20260 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a  intUsage[].omit.
20270 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e  ** is true, then
20280 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
20290 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65  is assumed to be
202a0 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62   fully handled b
202b0 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c  y the.** virtual
202c0 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f   table and is no
202d0 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20  t checked again 
202e0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  by SQLite..**.**
202f0 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20   The idxNum and 
20300 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72  idxPtr values ar
20310 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70  e recorded and p
20320 61 73 73 65 64 20 69 6e 74 6f 20 78 46 69 6c 74  assed into xFilt
20330 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  er..** sqlite3_f
20340 72 65 65 28 29 20 69 73 20 75 73 65 64 20 74 6f  ree() is used to
20350 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20   free idxPtr if 
20360 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
20370 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
20380 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  The orderByConsu
20390 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f  med means that o
203a0 75 74 70 75 74 20 66 72 6f 6d 20 78 46 69 6c 74  utput from xFilt
203b0 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e  er will occur in
203c0 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20  .** the correct 
203d0 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79  order to satisfy
203e0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
203f0 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20  ause so that no 
20400 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74  separate.** sort
20410 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75  ing step is requ
20420 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
20430 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61  estimatedCost va
20440 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61  lue is an estima
20450 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f  te of the cost o
20460 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70  f doing the.** p
20470 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70  articular lookup
20480 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f  .  A full scan o
20490 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e  f a table with N
204a0 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
204b0 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f  have.** a cost o
204c0 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73  f N.  A binary s
204d0 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65  earch of a table
204e0 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68   of N entries sh
204f0 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63  ould have a.** c
20500 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61  ost of approxima
20510 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a  tely log(N)..*/.
20520 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
20530 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a  ndex_info {.  /*
20540 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 63 6f 6e   Inputs */.  con
20550 73 74 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69  st int nConstrai
20560 6e 74 3b 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65  nt;     /* Numbe
20570 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20  r of entries in 
20580 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20  aConstraint */. 
20590 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
205a0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73  lite3_index_cons
205b0 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e  traint {.     in
205c0 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
205d0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
205e0 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73  n on left-hand s
205f0 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e  ide of constrain
20600 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  t */.     unsign
20610 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20  ed char op;     
20620 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e      /* Constrain
20630 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20  t operator */.  
20640 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
20650 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20   usable;     /* 
20660 54 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e  True if this con
20670 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c  straint is usabl
20680 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54  e */.     int iT
20690 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20  ermOffset;      
206a0 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65      /* Used inte
206b0 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e  rnally - xBestIn
206c0 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72  dex should ignor
206d0 65 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20  e */.  } *const 
206e0 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
206f0 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48    /* Table of WH
20700 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
20710 72 61 69 6e 74 73 20 2a 2f 0a 20 20 63 6f 6e 73  raints */.  cons
20720 74 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20  t int nOrderBy; 
20730 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
20740 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65   of terms in the
20750 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
20760 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 74 72 75   */.  const stru
20770 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
20780 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
20790 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
207a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
207b0 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
207c0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
207d0 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
207e0 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
207f0 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
20800 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 4f 72  /.  } *const aOr
20810 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 2f  derBy;         /
20820 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
20830 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f  lause */..  /* O
20840 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75  utputs */.  stru
20850 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
20860 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67  _constraint_usag
20870 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76  e {.    int argv
20880 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20  Index;          
20890 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74   /* if >0, const
208a0 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66  raint is part of
208b0 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72   argv to xFilter
208c0 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64   */.    unsigned
208d0 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20   char omit;     
208e0 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20   /* Do not code 
208f0 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20  a test for this 
20900 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
20910 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e 73 74 72  } *const aConstr
20920 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74  aintUsage;.  int
20930 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20   idxNum;        
20940 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
20950 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69  r used to identi
20960 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a  fy the index */.
20970 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20    char *idxStr; 
20980 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
20990 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79  String, possibly
209a0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
209b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f  qlite3_malloc */
209c0 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65  .  int needToFre
209d0 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a  eIdxStr;      /*
209e0 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69   Free idxStr usi
209f0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
20a00 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69  ) if true */.  i
20a10 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  nt orderByConsum
20a20 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  ed;       /* Tru
20a30 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61  e if output is a
20a40 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a  lready ordered *
20a50 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d  /.  double estim
20a60 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f  atedCost;      /
20a70 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74  * Estimated cost
20a80 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69   of using this i
20a90 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69  ndex */.};.#defi
20aa0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
20ab0 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20  CONSTRAINT_EQ   
20ac0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
20ad0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
20ae0 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69  NT_GT    4.#defi
20af0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
20b00 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20  CONSTRAINT_LE   
20b10 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
20b20 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
20b30 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66  NT_LT    16.#def
20b40 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
20b50 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20  _CONSTRAINT_GE  
20b60 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    32.#define SQL
20b70 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
20b80 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f  AINT_MATCH 64../
20b90 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
20ba0 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67  e is used to reg
20bb0 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64 75  ister a new modu
20bc0 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 6e 20  le name with an 
20bd0 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e 6e 65 63  SQLite.** connec
20be0 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 20 6e 61  tion.  Module na
20bf0 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67 69  mes must be regi
20c00 73 74 65 72 65 64 20 62 65 66 6f 72 65 20 63 72  stered before cr
20c10 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a 20 76 69  eating new.** vi
20c20 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 6e 20  rtual tables on 
20c30 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62  the module, or b
20c40 65 66 6f 72 65 20 75 73 69 6e 67 20 70 72 65 65  efore using pree
20c50 78 69 73 74 69 6e 67 20 76 69 72 74 75 61 6c 0a  xisting virtual.
20c60 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 74 68 65  ** tables of the
20c70 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e 74 20   module..*/.int 
20c80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
20c90 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  odule(.  sqlite3
20ca0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
20cb0 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
20cc0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
20cd0 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
20ce0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
20cf0 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
20d00 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
20d10 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
20d20 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
20d30 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *,    /* Method
20d40 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
20d50 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 20 20   */.  void *    
20d60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20d70 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
20d80 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
20d90 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  nect */.);../*.*
20da0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  * This routine i
20db0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 74  s identical to t
20dc0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
20dd0 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65 74 68 6f  e_module() metho
20de0 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63 65  d above,.** exce
20df0 70 74 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 77  pt that it allow
20e00 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
20e10 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 73 70  unction to be sp
20e20 65 63 69 66 69 65 64 2e 20 49 74 20 69 73 0a 2a  ecified. It is.*
20e30 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 78 70 65  * even more expe
20e40 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74 68  rimental than th
20e50 65 20 72 65 73 74 20 6f 66 20 74 68 65 20 76 69  e rest of the vi
20e60 72 74 75 61 6c 20 74 61 62 6c 65 73 20 41 50 49  rtual tables API
20e70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
20e80 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
20e90 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
20ea0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
20eb0 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
20ec0 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
20ed0 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
20ee0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
20ef0 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
20f00 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
20f10 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
20f20 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20  lite3_module *, 
20f30 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
20f40 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
20f50 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
20f60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
20f70 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
20f80 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
20f90 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73   */.  void(*xDes
20fa0 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20  troy)(void*)    
20fb0 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72   /* Module destr
20fc0 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a  uctor function *
20fd0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 45 76 65 72  /.);../*.** Ever
20fe0 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  y module impleme
20ff0 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73  ntation uses a s
21000 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66  ubclass of the f
21010 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
21020 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62  re.** to describ
21030 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69  e a particular i
21040 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 6d  nstance of the m
21050 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 73 75 62  odule.  Each sub
21060 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65  class will.** be
21070 20 74 61 79 6c 6f 72 65 64 20 74 6f 20 74 68 65   taylored to the
21080 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
21090 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d  of the module im
210a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 20  plementation.   
210b0 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73 65 20 6f  The.** purpose o
210c0 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73  f this superclas
210d0 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63  s is to define c
210e0 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68  ertain fields th
210f0 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a  at are common.**
21100 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69   to all module i
21110 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
21120 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
21130 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e  bles methods can
21140 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65   set an error me
21150 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69  ssage by assigni
21160 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  ng a.** string o
21170 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
21180 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 74  ite3_mprintf() t
21190 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20  o zErrMsg.  The 
211a0 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a  method should.**
211b0 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20   take care that 
211c0 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67  any prior string
211d0 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63   is freed by a c
211e0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  all to sqlite3_f
211f0 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f 72 20 74  ree().** prior t
21200 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65  o assigning a ne
21210 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72  w string to zErr
21220 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68 65 20  Msg.  After the 
21230 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
21240 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75 70   is delivered up
21250 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61   to the client a
21260 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
21270 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61  string will be a
21280 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
21290 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65 33  freed by sqlite3
212a0 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65 20  _free() and the 
212b0 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69  zErrMsg field wi
212c0 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e  ll be zeroed.  N
212d0 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69  ote.** that sqli
212e0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
212f0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  d sqlite3_free()
21300 20 61 72 65 20 75 73 65 64 20 6f 6e 20 74 68 65   are used on the
21310 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a   zErrMsg field.*
21320 2a 20 73 69 6e 63 65 20 76 69 72 74 75 61 6c 20  * since virtual 
21330 74 61 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f  tables are commo
21340 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  nly implemented 
21350 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 78 74 65  in loadable exte
21360 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20  nsions which.** 
21370 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  do not have acce
21380 73 73 20 74 6f 20 73 71 6c 69 74 65 33 4d 50 72  ss to sqlite3MPr
21390 69 6e 74 66 28 29 20 6f 72 20 73 71 6c 69 74 65  intf() or sqlite
213a0 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73 74 72 75  3Free()..*/.stru
213b0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
213c0 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  {.  const sqlite
213d0 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c  3_module *pModul
213e0 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c  e;  /* The modul
213f0 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75  e for this virtu
21400 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e  al table */.  in
21410 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20  t nRef;         
21420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
21430 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   Used internally
21440 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72   */.  char *zErr
21450 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20  Msg;            
21460 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
21470 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69  essage from sqli
21480 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f  te3_mprintf() */
21490 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61  .  /* Virtual ta
214a0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
214b0 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c  ons will typical
214c0 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ly add additiona
214d0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a  l fields */.};..
214e0 2f 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20  /* Every module 
214f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
21500 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ses a subclass o
21510 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
21520 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20  structure.** to 
21530 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73  describe cursors
21540 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f   that point into
21550 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
21560 6c 65 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a  le and are used.
21570 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75  ** to loop throu
21580 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  gh the virtual t
21590 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61  able.  Cursors a
215a0 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
215b0 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65   the.** xOpen me
215c0 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75  thod of the modu
215d0 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65  le.  Each module
215e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
215f0 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74  will define.** t
21600 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20  he content of a 
21610 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65  cursor structure
21620 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e   to suit its own
21630 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
21640 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78  is superclass ex
21650 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  ists in order to
21660 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f   define fields o
21670 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61  f the cursor tha
21680 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20  t.** are common 
21690 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  to all implement
216a0 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63  ations..*/.struc
216b0 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  t sqlite3_vtab_c
216c0 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65  ursor {.  sqlite
216d0 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20  3_vtab *pVtab;  
216e0 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74      /* Virtual t
216f0 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72  able of this cur
21700 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  sor */.  /* Virt
21710 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
21720 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
21730 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
21740 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
21750 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  /.};../*.** The 
21760 78 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e  xCreate and xCon
21770 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 6f 66 20  nect methods of 
21780 61 20 6d 6f 64 75 6c 65 20 75 73 65 20 74 68 65  a module use the
21790 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a   following API.*
217a0 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65  * to declare the
217b0 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d   format (the nam
217c0 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73  es and datatypes
217d0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29   of the columns)
217e0 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75   of.** the virtu
217f0 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69  al tables they i
21800 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74  mplement..*/.int
21810 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65   sqlite3_declare
21820 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20  _vtab(sqlite3*, 
21830 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 72 65  const char *zCre
21840 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a  ateTable);../*.*
21850 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
21860 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74   can provide alt
21870 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65  ernative impleme
21880 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63  ntations of func
21890 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74  tions.** using t
218a0 68 65 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e  he xFindFunction
218b0 20 6d 65 74 68 6f 64 2e 20 20 42 75 74 20 67 6c   method.  But gl
218c0 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66  obal versions of
218d0 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73   those functions
218e0 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69  .** must exist i
218f0 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76  n order to be ov
21900 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  erloaded..**.** 
21910 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73  This API makes s
21920 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72  ure a global ver
21930 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69  sion of a functi
21940 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63  on with a partic
21950 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64  ular.** name and
21960 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
21970 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49  eters exists.  I
21980 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69  f no such functi
21990 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66  on exists.** bef
219a0 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20  ore this API is 
219b0 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75  called, a new fu
219c0 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  nction is create
219d0 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  d.  The implemen
219e0 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
219f0 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c   new function al
21a00 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65  ways causes an e
21a10 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74  xception to be t
21a20 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68  hrown.  So.** th
21a30 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  e new function i
21a40 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61  s not good for a
21a50 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c  nything by itsel
21a60 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20  f.  Its only.** 
21a70 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65  purpose is to be
21a80 20 61 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 20   a place-holder 
21a90 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61  function that ca
21aa0 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a  n be overloaded.
21ab0 2a 2a 20 62 79 20 76 69 72 74 75 61 6c 20 74 61  ** by virtual ta
21ac0 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bles..**.** This
21ad0 20 41 50 49 20 73 68 6f 75 6c 64 20 62 65 20 63   API should be c
21ae0 6f 6e 73 69 64 65 72 65 64 20 70 61 72 74 20 6f  onsidered part o
21af0 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
21b00 62 6c 65 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  ble interface,.*
21b10 2a 20 77 68 69 63 68 20 69 73 20 65 78 70 65 72  * which is exper
21b20 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 75 62 6a  imental and subj
21b30 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a  ect to change..*
21b40 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76  /.int sqlite3_ov
21b50 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28  erload_function(
21b60 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
21b70 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c  char *zFuncName,
21b80 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a   int nArg);../*.
21b90 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
21ba0 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
21bb0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
21bc0 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62  defined above (b
21bd0 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63  ack up.** to a c
21be0 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c  omment remarkabl
21bf0 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69  y similar to thi
21c00 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e  s one) is curren
21c10 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
21c20 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
21c30 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
21c40 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
21c50 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
21c60 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
21c70 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
21c80 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
21c90 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
21ca0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
21cb0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
21cc0 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
21cd0 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73  hanism stablizes
21ce0 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
21cf0 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
21d00 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
21d10 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
21d20 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
21d30 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a  is comment..**.*
21d40 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ***** EXPERIMENT
21d50 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20  AL - subject to 
21d60 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e  change without n
21d70 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  otice **********
21d80 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  ****.*/../*.** C
21d90 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c  API3REF: A Handl
21da0 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f  e To An Open BLO
21db0 42 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  B.**.** An insta
21dc0 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  nce of the follo
21dd0 77 69 6e 67 20 6f 70 61 71 75 65 20 73 74 72 75  wing opaque stru
21de0 63 74 75 72 65 20 69 73 20 75 73 65 64 20 74 6f  cture is used to
21df0 20 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 20 61   .** represent a
21e00 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 2e 20 20  n blob-handle.  
21e10 41 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 20 69 73  A blob-handle is
21e20 20 63 72 65 61 74 65 64 20 62 79 0a 2a 2a 20 5b   created by.** [
21e30 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
21e40 6e 28 29 5d 20 61 6e 64 20 64 65 73 74 72 6f 79  n()] and destroy
21e50 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
21e60 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  lob_close()]..**
21e70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   The [sqlite3_bl
21e80 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b  ob_read()] and [
21e90 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
21ea0 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  te()] interfaces
21eb0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
21ec0 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  to read or write
21ed0 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f   small subsectio
21ee0 6e 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 2e 0a  ns of the blob..
21ef0 2a 2a 20 54 68 65 20 5b 73 71 6c 74 69 65 33 5f  ** The [sqltie3_
21f00 62 6c 6f 62 5f 73 69 7a 65 28 29 5d 20 69 6e 74  blob_size()] int
21f10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
21f20 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  he size of the.*
21f30 2a 20 62 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e  * blob in bytes.
21f40 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
21f50 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ct sqlite3_blob 
21f60 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f  sqlite3_blob;../
21f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
21f80 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49  pen A BLOB For I
21f90 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a  ncremental I/O.*
21fa0 2a 0a 2a 2a 20 4f 70 65 6e 20 61 20 68 61 6e 64  *.** Open a hand
21fb0 6c 65 20 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c  le to the blob l
21fc0 6f 63 61 74 65 64 20 69 6e 20 72 6f 77 20 69 52  ocated in row iR
21fd0 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c  ow,, column zCol
21fe0 75 6d 6e 2c 20 0a 2a 2a 20 74 61 62 6c 65 20 7a  umn, .** table z
21ff0 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73  Table in databas
22000 65 20 7a 44 62 2e 20 69 2e 65 2e 20 74 68 65 20  e zDb. i.e. the 
22010 73 61 6d 65 20 62 6c 6f 62 20 74 68 61 74 20 77  same blob that w
22020 6f 75 6c 64 0a 2a 2a 20 62 65 20 73 65 6c 65 63  ould.** be selec
22030 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ted by:.**.** <p
22040 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43  re>.**     SELEC
22050 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a  T zColumn FROM z
22060 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20  Db.zTable WHERE 
22070 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a  rowid = iRow;.**
22080 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 49 66   </pre>.**.** If
22090 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
220a0 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  eter is non-zero
220b0 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70  , the blob is op
220c0 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61  ened for .** rea
220d0 64 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65  d and write acce
220e0 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72  ss. If it is zer
220f0 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f  o, the blob is o
22100 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 0a  pened for read .
22110 2a 2a 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ** access..**.**
22120 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
22130 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
22140 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77  rned and the new
22150 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c   .** [sqlite3_bl
22160 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65  ob | blob handle
22170 5d 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  ] is written to 
22180 2a 70 70 42 6c 6f 62 2e 0a 2a 2a 20 4f 74 68 65  *ppBlob..** Othe
22190 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 63  rwise an error c
221a0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
221b0 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  and .** any valu
221c0 65 20 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70  e written to *pp
221d0 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f 74 20  Blob should not 
221e0 62 65 20 75 73 65 64 20 62 79 20 74 68 65 20 63  be used by the c
221f0 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 73 20 66  aller..** This f
22200 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65  unction sets the
22210 20 64 61 74 61 62 61 73 65 2d 68 61 6e 64 6c 65   database-handle
22220 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
22230 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73  message.** acces
22240 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74  sible via [sqlit
22250 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e  e3_errcode()] an
22260 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
22270 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
22280 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a  ite3_blob_open(.
22290 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f    sqlite3*,.  co
222a0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20  nst char *zDb,. 
222b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
222c0 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  ble,.  const cha
222d0 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71  r *zColumn,.  sq
222e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77  lite3_int64 iRow
222f0 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20  ,.  int flags,. 
22300 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a   sqlite3_blob **
22310 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ppBlob.);../*.**
22320 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c 6f 73   CAPI3REF:  Clos
22330 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a  e A BLOB Handle.
22340 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61 6e 20 6f  **.** Close an o
22350 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  pen [sqlite3_blo
22360 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d  b | blob handle]
22370 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22380 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69  _blob_close(sqli
22390 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
223a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 52  .** CAPI3REF:  R
223b0 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f  eturn The Size O
223c0 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a  f An Open BLOB.*
223d0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
223e0 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66  size in bytes of
223f0 20 74 68 65 20 62 6c 6f 62 20 61 63 63 65 73 73   the blob access
22400 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f 70 65  ible via the ope
22410 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  n .** [sqlite3_b
22420 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c  lob | blob-handl
22430 65 5d 20 70 61 73 73 65 64 20 61 73 20 61 6e 20  e] passed as an 
22440 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74  argument..*/.int
22450 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79   sqlite3_blob_by
22460 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  tes(sqlite3_blob
22470 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   *);../*.** CAPI
22480 33 52 45 46 3a 20 20 52 65 61 64 20 44 61 74 61  3REF:  Read Data
22490 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63   From A BLOB Inc
224a0 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a  rementally.**.**
224b0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
224c0 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64  s used to read d
224d0 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e  ata from an open
224e0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c   .** [sqlite3_bl
224f0 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65  ob | blob-handle
22500 5d 20 69 6e 74 6f 20 61 20 63 61 6c 6c 65 72 20  ] into a caller 
22510 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
22520 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66 20 64  .** n bytes of d
22530 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69  ata are copied i
22540 6e 74 6f 20 62 75 66 66 65 72 0a 2a 2a 20 7a 20  nto buffer.** z 
22550 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c  from the open bl
22560 6f 62 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  ob, starting at 
22570 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
22580 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
22590 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  , SQLITE_OK is r
225a0 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69  eturned. Otherwi
225b0 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49  se, an .** [SQLI
225c0 54 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74  TE_ERROR | SQLit
225d0 65 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72  e error code] or
225e0 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   an.** [SQLITE_I
225f0 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
22600 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
22610 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   is returned..*/
22620 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
22630 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62  b_read(sqlite3_b
22640 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 7a 2c 20  lob *, void *z, 
22650 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
22660 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
22670 33 52 45 46 3a 20 20 57 72 69 74 65 20 44 61 74  3REF:  Write Dat
22680 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e  a Into A BLOB In
22690 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a  crementally.**.*
226a0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
226b0 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65  is used to write
226c0 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70   data into an op
226d0 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
226e0 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64  blob | blob-hand
226f0 6c 65 5d 20 66 72 6f 6d 20 61 20 75 73 65 72 20  le] from a user 
22700 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
22710 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66 20 64  .** n bytes of d
22720 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66  ata are copied f
22730 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 0a 2a  rom the buffer.*
22740 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
22750 7a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20  z into the open 
22760 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 20 61  blob, starting a
22770 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  t offset iOffset
22780 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
22790 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
227a0 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73  lob-handle] pass
227b0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
227c0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  argument.** was 
227d0 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 20 77  not opened for w
227e0 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67  riting (the flag
227f0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  s parameter to [
22800 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
22810 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73 20 7a 65 72  n()].*** was zer
22820 6f 29 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  o), this functio
22830 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  n returns [SQLIT
22840 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a  E_READONLY]..**.
22850 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
22860 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79   may only modify
22870 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66   the contents of
22880 20 74 68 65 20 62 6c 6f 62 2c 20 69 74 20 69 73   the blob, it is
22890 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
228a0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65   to increase the
228b0 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20   size of a blob 
228c0 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 20  using this API. 
228d0 49 66 0a 2a 2a 20 6f 66 66 73 65 74 20 69 4f 66  If.** offset iOf
228e0 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
228f0 6e 20 6e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n n bytes from t
22900 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 62 6c  he end of the bl
22910 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ob, .** [SQLITE_
22920 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
22930 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
22940 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a  s written..**.**
22950 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c   On success, SQL
22960 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
22970 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61  ed. Otherwise, a
22980 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
22990 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65 72 72  ROR | SQLite err
229a0 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  or code] or an.*
229b0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  * [SQLITE_IOERR_
229c0 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
229d0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
229e0 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  eturned..*/.int 
229f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
22a00 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  te(sqlite3_blob 
22a10 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  *, const void *z
22a20 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66  , int n, int iOf
22a30 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  fset);../*.** CA
22a40 50 49 33 52 45 46 3a 20 20 56 69 72 74 75 61 6c  PI3REF:  Virtual
22a50 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a   File System Obj
22a60 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72  ects.**.** A vir
22a70 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20  tual filesystem 
22a80 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c  (VFS) is an [sql
22a90 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
22aa0 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
22ab0 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74  uses to interact
22ac0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64  .** with the und
22ad0 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
22ae0 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20  g system.  Most 
22af0 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68  builds come with
22b00 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66   a.** single def
22b10 61 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73  ault VFS that is
22b20 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
22b30 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74   the host comput
22b40 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73  er..** New VFSes
22b50 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
22b60 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20  ed and existing 
22b70 56 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72  VFSes can be unr
22b80 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68  egistered..** Th
22b90 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  e following inte
22ba0 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
22bb0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ded..**.** The s
22bc0 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
22bd0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
22be0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
22bf0 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73   a VFS given its
22c00 0a 2a 2a 20 6e 61 6d 65 2e 20 20 4e 61 6d 65 73  .** name.  Names
22c10 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 74   are case sensit
22c20 69 76 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  ive.  If there i
22c30 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55  s no match, a NU
22c40 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  LL.** pointer is
22c50 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 7a   returned.  If z
22c60 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20  VfsName is NULL 
22c70 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
22c80 20 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 74 75   .** VFS is retu
22c90 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  rned..**.** New 
22ca0 56 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74  VFSes are regist
22cb0 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65  ered with sqlite
22cc0 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
22cd0 2e 20 20 45 61 63 68 0a 2a 2a 20 6e 65 77 20 56  .  Each.** new V
22ce0 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64  FS becomes the d
22cf0 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 68  efault VFS if th
22d00 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20  e makeDflt flag 
22d10 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73  is set..** The s
22d20 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20 72  ame VFS can be r
22d30 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
22d40 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74  le times without
22d50 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d   injury..** To m
22d60 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20  ake an existing 
22d70 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66  VFS into the def
22d80 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74  ault VFS, regist
22d90 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77  er it again.** w
22da0 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74  ith the makeDflt
22db0 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74   flag set.  If t
22dc0 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53  wo different VFS
22dd0 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73  es with the.** s
22de0 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67  ame name are reg
22df0 69 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68  istered, the beh
22e00 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
22e10 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53  ed.  If a.** VFS
22e20 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
22e30 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20  ith a name that 
22e40 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
22e50 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74  pty string,.** t
22e60 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
22e70 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
22e80 2a 20 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65 72  * .** Unregister
22e90 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20   a VFS with the 
22ea0 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
22eb0 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61  gister() interfa
22ec0 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 65  ce..** If the de
22ed0 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72  fault VFS is unr
22ee0 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68  egistered, anoth
22ef0 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e  er VFS is chosen
22f00 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   as.** the defau
22f10 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20  lt.  The choice 
22f20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53 20  for the new VFS 
22f30 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2f  is arbitrary..*/
22f40 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71  .sqlite3_vfs *sq
22f50 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63  lite3_vfs_find(c
22f60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e  onst char *zVfsN
22f70 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ame);.int sqlite
22f80 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73  3_vfs_register(s
22f90 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
22fa0 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20   makeDflt);.int 
22fb0 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
22fc0 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
22fd0 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  fs*);../*.** CAP
22fe0 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a  I3REF: Mutexes.*
22ff0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
23000 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
23010 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72  routines for thr
23020 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69  ead.** synchroni
23030 7a 61 74 69 6f 6e 2e 20 20 54 68 6f 75 67 68 20  zation.  Though 
23040 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65  they are intende
23050 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a  d for internal.*
23060 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c  * use by SQLite,
23070 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73   code that links
23080 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20   against SQLite 
23090 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20  is.** permitted 
230a0 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68  to use any of th
230b0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
230c0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73  .** The SQLite s
230d0 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61  ource code conta
230e0 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ins multiple imp
230f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 0a 2a 2a  lementations .**
23100 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78 20   of these mutex 
23110 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70  routines.  An ap
23120 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d  propriate implem
23130 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73  entation.** is s
23140 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69  elected automati
23150 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65  cally at compile
23160 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c  -time.  The foll
23170 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65  owing.** impleme
23180 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61  ntations are ava
23190 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51  ilable in the SQ
231a0 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a  Lite core:.**.**
231b0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20   <ul>.** <li>   
231c0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
231d0 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  READ.** <li>   S
231e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 49 4e 0a  QLITE_MUTEX_WIN.
231f0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
23200 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c  _MUTEX_NOOP.** <
23210 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
23220 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50  QLITE_MUTEX_NOOP
23230 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
23240 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74  is a set of rout
23250 69 6e 65 73 20 0a 2a 2a 20 74 68 61 74 20 64 6f  ines .** that do
23260 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69  es no real locki
23270 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70  ng and is approp
23280 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e  riate for use in
23290 20 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68   .** a single-th
232a0 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
232b0 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  on.  The SQLITE_
232c0 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a  MUTEX_PTHREAD.**
232d0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
232e0 58 5f 57 49 4e 20 69 6d 70 6c 65 6d 65 6e 74 61  X_WIN implementa
232f0 74 69 6f 6e 73 20 61 72 65 20 61 70 70 72 6f 70  tions are approp
23300 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 75 73 65  riate for.** use
23310 20 6f 6e 20 75 6e 69 78 20 61 6e 64 20 77 69 6e   on unix and win
23320 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  dows..** .** If 
23330 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
23340 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
23350 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
23360 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
23370 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
23380 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
23390 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
233a0 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
233b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
233c0 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
233d0 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 20 54   the library.  T
233e0 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e 74 65  he.** mutex inte
233f0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 64  rface routines d
23400 65 66 69 6e 65 64 20 68 65 72 65 20 62 65 63 6f  efined here beco
23410 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a 20 72  me external.** r
23420 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74 68 65  eferences in the
23430 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
23440 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c 65 6d  for which implem
23450 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73  entations.** mus
23460 74 20 62 65 20 70 72 6f 76 69 64 65 64 20 62 79  t be provided by
23470 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
23480 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69 74 79  .  This facility
23490 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20 61 70   allows an.** ap
234a0 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 6c  plication that l
234b0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c  inks against SQL
234c0 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65 20 69  ite to provide i
234d0 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a 2a 20  ts own mutex.** 
234e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
234f0 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
23500 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 69   modify the SQLi
23510 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  te core..**.** T
23520 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
23530 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  _alloc() routine
23540 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77   allocates a new
23550 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65  .** mutex and re
23560 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
23570 74 6f 20 69 74 2e 20 20 49 66 20 69 74 20 72 65  to it.  If it re
23580 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  turns NULL.** th
23590 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  at means that a 
235a0 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20  mutex could not 
235b0 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53  be allocated.  S
235c0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e  QLite.** will un
235d0 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61  wind its stack a
235e0 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  nd return an err
235f0 6f 72 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  or.  The argumen
23600 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
23610 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73  mutex_alloc() is
23620 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
23630 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a  teger constants:
23640 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
23650 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
23660 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20  X_FAST.** <li>  
23670 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
23680 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  URSIVE.** <li>  
23690 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
236a0 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c  TIC_MASTER.** <l
236b0 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
236c0 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c  _STATIC_MEM.** <
236d0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
236e0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a  X_STATIC_MEM2.**
236f0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
23700 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a  TEX_STATIC_PRNG.
23710 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
23720 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
23730 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
23740 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f  The first two co
23750 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73 71  nstants cause sq
23760 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
23770 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a  c() to create.**
23780 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 54   a new mutex.  T
23790 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20  he new mutex is 
237a0 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53  recursive when S
237b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
237c0 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64  RSIVE.** is used
237d0 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61   but not necessa
237e0 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c  rily so when SQL
237f0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69  ITE_MUTEX_FAST i
23800 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  s used..** The m
23810 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
23820 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
23830 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74  d to make a dist
23840 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
23850 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
23860 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51  RECURSIVE and SQ
23870 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
23880 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  if it does.** no
23890 74 20 77 61 6e 74 20 74 6f 2e 20 20 42 75 74 20  t want to.  But 
238a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
238b0 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75 72   request a recur
238c0 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a  sive mutex in.**
238d0 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74 20   cases where it 
238e0 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65  really needs one
238f0 2e 20 20 49 66 20 61 20 66 61 73 74 65 72 20 6e  .  If a faster n
23900 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74  on-recursive mut
23910 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ex.** implementa
23920 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
23930 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c  e on the host pl
23940 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65  atform, the mute
23950 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d  x subsystem.** m
23960 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 63 68  ight return such
23970 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70   a mutex in resp
23980 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d  onse to SQLITE_M
23990 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a  UTEX_FAST..**.**
239a0 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77   The other allow
239b0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ed parameters to
239c0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
239d0 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75  lloc() each retu
239e0 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  rn.** a pointer 
239f0 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65  to a static pree
23a00 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20  xisting mutex.  
23a10 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75 74 65  Four static mute
23a20 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  xes are.** used 
23a30 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  by the current v
23a40 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
23a50 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
23a60 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
23a70 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  may add addition
23a80 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  al static mutexe
23a90 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78  s.  Static mutex
23aa0 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72  es are for inter
23ab0 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
23ac0 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c  Lite only.  Appl
23ad0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
23ae0 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73  e SQLite mutexes
23af0 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f   should.** use o
23b00 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20  nly the dynamic 
23b10 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64  mutexes returned
23b20 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   by SQLITE_MUTEX
23b30 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49  _FAST or.** SQLI
23b40 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
23b50 56 45 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  VE..**.** Note t
23b60 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68  hat if one of th
23b70 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  e dynamic mutex 
23b80 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49  parameters (SQLI
23b90 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
23ba0 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   or SQLITE_MUTEX
23bb0 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75  _RECURSIVE) is u
23bc0 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33  sed then sqlite3
23bd0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a  _mutex_alloc().*
23be0 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66  * returns a diff
23bf0 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65  erent mutex on e
23c00 76 65 72 79 20 63 61 6c 6c 2e 20 20 42 75 74 20  very call.  But 
23c10 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 20 0a  for the static .
23c20 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20  ** mutex types, 
23c30 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69  the same mutex i
23c40 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76  s returned on ev
23c50 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61  ery call that ha
23c60 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79  s.** the same ty
23c70 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  pe number..**.**
23c80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
23c90 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
23ca0 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
23cb0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
23cc0 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
23cd0 6d 75 74 65 78 2e 20 20 53 51 4c 69 74 65 20 69  mutex.  SQLite i
23ce0 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61  s careful to dea
23cf0 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a  llocate every.**
23d00 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74   dynamic mutex t
23d10 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73  hat it allocates
23d20 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d  .  The dynamic m
23d30 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20  utexes must not 
23d40 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65 20 77 68  be in .** use wh
23d50 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c  en they are deal
23d60 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70  located.  Attemp
23d70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61  ting to dealloca
23d80 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d  te a static.** m
23d90 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20  utex results in 
23da0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
23db0 6f 72 2e 20 20 53 51 4c 69 74 65 20 6e 65 76 65  or.  SQLite neve
23dc0 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a  r deallocates.**
23dd0 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e   a static mutex.
23de0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23df0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
23e00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
23e10 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65  ex_try() routine
23e20 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20  s attempt.** to 
23e30 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 20  enter a mutex.  
23e40 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
23e50 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 74  d is already wit
23e60 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a  hin the mutex,.*
23e70 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
23e80 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f  enter() will blo
23e90 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  ck and sqlite3_m
23ea0 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20  utex_try() will 
23eb0 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
23ec0 5f 42 55 53 59 2e 20 20 54 68 65 20 73 71 6c 69  _BUSY.  The sqli
23ed0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
23ee0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23ef0 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 75  s SQLITE_OK.** u
23f00 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65  pon successful e
23f10 6e 74 72 79 2e 20 20 4d 75 74 65 78 65 73 20 63  ntry.  Mutexes c
23f20 72 65 61 74 65 64 20 75 73 69 6e 67 20 53 51 4c  reated using SQL
23f30 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
23f40 49 56 45 20 63 61 6e 0a 2a 2a 20 62 65 20 65 6e  IVE can.** be en
23f50 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
23f60 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65  imes by the same
23f70 20 74 68 72 65 61 64 2e 20 20 49 6e 20 73 75 63   thread.  In suc
23f80 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20  h cases the,.** 
23f90 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78  mutex must be ex
23fa0 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75  ited an equal nu
23fb0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65  mber of times be
23fc0 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72  fore another thr
23fd0 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72  ead.** can enter
23fe0 2e 20 20 49 66 20 74 68 65 20 73 61 6d 65 20 74  .  If the same t
23ff0 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65  hread tries to e
24000 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 20 6b  nter any other k
24010 69 6e 64 20 6f 66 20 6d 75 74 65 78 0a 2a 2a 20  ind of mutex.** 
24020 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
24030 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
24040 75 6e 64 65 66 69 6e 65 64 2e 20 20 20 53 51 4c  undefined.   SQL
24050 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65  ite will never e
24060 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62  xhibit.** such b
24070 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f  ehavior in its o
24080 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65  wn use of mutexe
24090 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
240a0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
240b0 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74 73  () routine exits
240c0 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77 61   a mutex that wa
240d0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
240e0 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20 73  entered by the s
240f0 61 6d 65 20 74 68 72 65 61 64 2e 20 20 54 68 65  ame thread.  The
24100 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
24110 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65  undefined if the
24120 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75   mutex is not cu
24130 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
24140 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e  by the.** callin
24150 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e  g thread or is n
24160 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c  ot currently all
24170 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20  ocated.  SQLite 
24180 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f  will.** never do
24190 20 65 69 74 68 65 72 2e 0a 2a 2a 0a 2a 2a 20 53   either..**.** S
241a0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
241b0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20  3_mutex_held()] 
241c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  and [sqlite3_mut
241d0 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a  ex_notheld()]..*
241e0 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  /.sqlite3_mutex 
241f0 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  *sqlite3_mutex_a
24200 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
24210 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
24220 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ee(sqlite3_mutex
24230 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
24240 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c  _mutex_enter(sql
24250 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e  ite3_mutex*);.in
24260 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
24270 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  try(sqlite3_mute
24280 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  x*);.void sqlite
24290 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71  3_mutex_leave(sq
242a0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a  lite3_mutex*);..
242b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
242c0 4d 75 74 65 78 20 56 65 72 69 66 63 61 74 69 6f  Mutex Verifcatio
242d0 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
242e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
242f0 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71  ex_held() and sq
24300 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
24310 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a  eld() routines.*
24320 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  * are intended f
24330 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73  or use inside as
24340 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
24350 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  s.  The SQLite c
24360 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65  ore.** never use
24370 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  s these routines
24380 20 65 78 63 65 70 74 20 69 6e 73 69 64 65 20 61   except inside a
24390 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64 20 61  n assert() and a
243a0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
243b0 72 65 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f  re advised to fo
243c0 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66  llow the lead of
243d0 20 74 68 65 20 63 6f 72 65 2e 20 20 54 68 65 20   the core.  The 
243e0 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f  core only.** pro
243f0 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61  vides implementa
24400 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20  tions for these 
24410 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74  routines when it
24420 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
24430 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
24440 44 45 42 55 47 20 66 6c 61 67 2e 20 20 45 78 74  DEBUG flag.  Ext
24450 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c  ernal mutex impl
24460 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
24470 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64  re only required
24480 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73   to provide thes
24490 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51  e routines if SQ
244a0 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a  LITE_DEBUG is.**
244b0 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20   defined and if 
244c0 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65  NDEBUG is not de
244d0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
244e0 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  se routines shou
244f0 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  ld return true i
24500 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74  f the mutex in t
24510 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  heir argument.**
24520 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20   is held or not 
24530 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65  held, respective
24540 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69  ly, by the calli
24550 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  ng thread..**.**
24560 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
24570 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69  ion is not requi
24580 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20  red to provided 
24590 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
245a0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
245b0 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b  at actually work
245c0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6d 70 6c  ..** If the impl
245d0 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
245e0 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b  not provide work
245f0 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ing.** versions 
24600 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
24610 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20  s, it should at 
24620 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74  least provide st
24630 75 62 73 0a 2a 2a 20 74 68 61 74 20 61 6c 77 61  ubs.** that alwa
24640 79 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  ys return true s
24650 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20  o that one does 
24660 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73  not get spurious
24670 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e 20 66 61  .** assertion fa
24680 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  ilures..**.** If
24690 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
246a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
246b0 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  eld() is a NULL 
246c0 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20  pointer then.** 
246d0 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  the routine shou
246e0 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 54 68  ld return 1.  Th
246f0 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72  is seems counter
24700 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65  -intuitive since
24710 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20  .** clearly the 
24720 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20  mutex cannot be 
24730 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20  held if it does 
24740 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20  not exist.  But 
24750 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f  the.** the reaso
24760 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73  n the mutex does
24770 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65   not exist is be
24780 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20  cause the build 
24790 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20  is not.** using 
247a0 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65  mutexes.  And we
247b0 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65   do not want the
247c0 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69   assert() contai
247d0 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  ning the.** call
247e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
247f0 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c  x_held() to fail
24800 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  , so a non-zero 
24810 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65  return is.** the
24820 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69   appropriate thi
24830 6e 67 20 74 6f 20 64 6f 2e 20 20 54 68 65 20 73  ng to do.  The s
24840 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
24850 68 65 6c 64 28 29 20 0a 2a 2a 20 69 6e 74 65 72  held() .** inter
24860 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f  face should also
24870 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67   return 1 when g
24880 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  iven a NULL poin
24890 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ter..*/.int sqli
248a0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73  te3_mutex_held(s
248b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
248c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
248d0 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65  x_notheld(sqlite
248e0 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a  3_mutex*);../*.*
248f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
24900 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54 68  x Types.**.** Th
24910 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
24920 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66  _alloc()] interf
24930 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ace takes a sing
24940 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77  le argument.** w
24950 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74  hich is one of t
24960 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
24970 73 74 61 6e 74 73 2e 0a 2a 2f 0a 23 64 65 66 69  stants..*/.#defi
24980 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
24990 46 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20  FAST            
249a0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
249b0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
249c0 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  E        1.#defi
249d0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
249e0 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20  STATIC_MASTER   
249f0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
24a00 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
24a10 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73  EM       3  /* s
24a20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
24a30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24a40 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
24a50 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 73  EM2      4  /* s
24a60 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
24a70 65 6d 6f 72 79 28 29 20 2a 2f 0a 23 64 65 66 69  emory() */.#defi
24a80 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
24a90 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20  STATIC_PRNG     
24aa0 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72   5  /* sqlite3_r
24ab0 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69  andom() */.#defi
24ac0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
24ad0 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20  STATIC_LRU      
24ae0 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20   6  /* lru page 
24af0 6c 69 73 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  list */.../*.** 
24b00 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68  Undo the hack th
24b10 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61  at converts floa
24b20 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73  ting point types
24b30 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a   to integer for.
24b40 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f  ** builds on pro
24b50 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20  cessors without 
24b60 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
24b70 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65  upport..*/.#ifde
24b80 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
24b90 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75  OATING_POINT.# u
24ba0 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64  ndef double.#end
24bb0 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  if..#ifdef __cpl
24bc0 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64  usplus.}  /* End
24bd0 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e 20   of the 'extern 
24be0 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65  "C"' block */.#e
24bf0 6e 64 69 66 0a 23 65 6e 64 69 66 0a              ndif.#endif.