/ Hex Artifact Content
Login

Artifact 1b651cd409f3aed2e78e47f551b4a92f47dd57f4:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 32 36 30 20 32 30 30 37 2f  in,v 1.260 2007/
05f0: 30 39 2f 31 37 20 30 36 3a 30 36 3a 33 39 20 64  09/17 06:06:39 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 54 65 73 74  * CAPI3REF: Test
10a0: 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c   To See If The L
10b0: 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64  ibrary Is Thread
10c0: 73 61 66 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  safe.**.** This 
10d0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10e0: 54 52 55 45 20 28 6e 6f 6e 7a 65 72 6f 29 20 69  TRUE (nonzero) i
10f0: 66 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d  f SQLite was com
1100: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 61 6c  piled with.** al
1110: 6c 20 6f 66 20 69 74 73 20 6d 75 74 65 78 65 73  l of its mutexes
1120: 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 69 73 20   enabled and is 
1130: 74 68 75 73 20 74 68 72 65 61 64 73 61 66 65 2e  thus threadsafe.
1140: 20 20 49 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20    It returns.** 
1150: 7a 65 72 6f 20 69 66 20 74 68 65 20 70 61 72 74  zero if the part
1160: 69 63 75 6c 61 72 20 62 75 69 6c 64 20 69 73 20  icular build is 
1170: 66 6f 72 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  for single-threa
1180: 64 65 64 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  ded operation.**
1190: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 61   only..**.** Rea
11a0: 6c 6c 79 20 61 6c 6c 20 74 68 69 73 20 72 6f 75  lly all this rou
11b0: 74 69 6e 65 20 64 6f 65 73 20 69 73 20 72 65 74  tine does is ret
11c0: 75 72 6e 20 74 72 75 65 20 69 66 20 53 51 4c 69  urn true if SQLi
11d0: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a  te was compiled.
11e0: 2a 2a 20 77 69 74 68 20 74 68 65 20 2d 44 53 51  ** with the -DSQ
11f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1200: 31 20 6f 70 74 69 6f 6e 20 61 6e 64 20 66 61 6c  1 option and fal
1210: 73 65 20 69 66 0a 2a 2a 20 63 6f 6d 70 69 6c 65  se if.** compile
1220: 64 20 77 69 74 68 20 2d 44 53 51 4c 49 54 45 5f  d with -DSQLITE_
1230: 54 48 52 45 41 44 53 41 46 45 3d 30 2e 20 20 49  THREADSAFE=0.  I
1240: 66 20 53 51 4c 69 74 65 20 75 73 65 73 20 61 6e  f SQLite uses an
1250: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  .** application-
1260: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 73 75  defined mutex su
1270: 62 73 79 73 74 65 6d 2c 20 6d 61 6c 6c 6f 63 20  bsystem, malloc 
1280: 73 75 62 73 79 73 74 65 6d 2c 20 63 6f 6c 6c 61  subsystem, colla
1290: 74 69 6e 67 0a 2a 2a 20 73 65 71 75 65 6e 63 65  ting.** sequence
12a0: 2c 20 56 46 53 2c 20 53 51 4c 20 66 75 6e 63 74  , VFS, SQL funct
12b0: 69 6f 6e 2c 20 70 72 6f 67 72 65 73 73 20 63 61  ion, progress ca
12c0: 6c 6c 62 61 63 6b 2c 20 63 6f 6d 6d 69 74 20 68  llback, commit h
12d0: 6f 6f 6b 2c 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ook,.** extensio
12e0: 6e 2c 20 6f 72 20 6f 74 68 65 72 20 61 63 63 65  n, or other acce
12f0: 73 73 6f 72 69 65 73 20 61 6e 64 20 74 68 65 73  ssories and thes
1300: 65 20 61 64 64 2d 6f 6e 73 20 61 72 65 20 6e 6f  e add-ons are no
1310: 74 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 65 2c  t.** threadsafe,
1320: 20 74 68 65 6e 20 63 6c 65 61 72 6c 79 20 74 68   then clearly th
1330: 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 77 69  e combination wi
1340: 6c 6c 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ll not be thread
1350: 73 61 66 65 0a 2a 2a 20 65 69 74 68 65 72 2e 20  safe.** either. 
1360: 20 48 65 6e 63 65 2c 20 74 68 69 73 20 72 6f 75   Hence, this rou
1370: 74 69 6e 65 20 6e 65 76 65 72 20 72 65 70 6f 72  tine never repor
1380: 74 73 20 74 68 61 74 20 74 68 65 20 6c 69 62 72  ts that the libr
1390: 61 72 79 0a 2a 2a 20 69 73 20 67 75 61 72 61 6e  ary.** is guaran
13a0: 74 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  teed to be threa
13b0: 64 73 61 66 65 2c 20 6f 6e 6c 79 20 77 68 65 6e  dsafe, only when
13c0: 20 69 74 20 69 73 20 67 75 61 72 61 6e 74 65 65   it is guarantee
13d0: 64 20 6e 6f 74 0a 2a 2a 20 74 6f 20 62 65 2e 0a  d not.** to be..
13e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 6e  **.** This is an
13f0: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 41 50   experimental AP
1400: 49 20 61 6e 64 20 6d 61 79 20 67 6f 20 61 77 61  I and may go awa
1410: 79 20 6f 72 20 63 68 61 6e 67 65 20 69 6e 20 66  y or change in f
1420: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
1430: 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
1440: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
1450: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
1460: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
1470: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
1480: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
1490: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
14a0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
14b0: 79 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  y pointer to an 
14c0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a  instance of the.
14d0: 2a 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  ** opaque struct
14e0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
14f0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1500: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1510: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1520: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1530: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
1540: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1550: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1560: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
1570: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1580: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
1590: 74 72 75 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20  tructors.** and 
15a0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
15b0: 5d 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63  ] is its destruc
15c0: 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20  tor.  There are 
15d0: 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72  many other inter
15e0: 66 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 61  faces.** (such a
15f0: 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1600: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
1610: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1620: 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  on()], and.** [s
1630: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1640: 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62  out()] to name b
1650: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61  ut three) that a
1660: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68  re methods on th
1670: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f  is.** object..*/
1680: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1690: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
16a0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
16b0: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
16c0: 72 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 53 6f  r Types.**.** So
16d0: 6d 65 20 63 6f 6d 70 69 6c 65 72 73 20 64 6f 20  me compilers do 
16e0: 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65 20  not support the 
16f0: 22 6c 6f 6e 67 20 6c 6f 6e 67 22 20 64 61 74 61  "long long" data
1700: 74 79 70 65 2e 20 20 53 6f 20 77 65 20 68 61 76  type.  So we hav
1710: 65 0a 2a 2a 20 74 6f 20 64 6f 20 63 6f 6d 70 69  e.** to do compi
1720: 6c 65 72 2d 73 70 65 63 69 66 69 63 20 74 79 70  ler-specific typ
1730: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
1740: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
1750: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
1760: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
1770: 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1780: 69 6f 6e 73 20 72 65 71 75 69 72 65 20 61 20 36  ions require a 6
1790: 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 61 72  4-bit integer ar
17a0: 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 6f 73  guments..** Thos
17b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
17c0: 20 64 65 63 6c 61 72 65 64 20 75 73 69 6e 67 20   declared using 
17d0: 74 68 69 73 20 74 79 70 65 64 65 66 2e 0a 2a 2f  this typedef..*/
17e0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49  .#ifdef SQLITE_I
17f0: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65  NT64_TYPE.  type
1800: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
1810: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74  _TYPE sqlite_int
1820: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
1830: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e  signed SQLITE_IN
1840: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
1850: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65  uint64;.#elif de
1860: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20  fined(_MSC_VER) 
1870: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52  || defined(__BOR
1880: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64  LANDC__).  typed
1890: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ef __int64 sqlit
18a0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
18b0: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e  ef unsigned __in
18c0: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  t64 sqlite_uint6
18d0: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64  4;.#else.  typed
18e0: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ef long long int
18f0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
1900: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
1910: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  d long long int 
1920: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
1930: 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71  endif.typedef sq
1940: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
1950: 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65  e3_int64;.typede
1960: 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  f sqlite_uint64 
1970: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a  sqlite3_uint64;.
1980: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c  ./*.** If compil
1990: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73  ing for a proces
19a0: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66  sor that lacks f
19b0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75  loating point su
19c0: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69  pport,.** substi
19d0: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72  tute integer for
19e0: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 0a   floating-point.
19f0: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
1a00: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
1a10: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f  OINT.# define do
1a20: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  uble sqlite3_int
1a30: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  64.#endif../*.**
1a40: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69   CAPI3REF: Closi
1a50: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  ng A Database Co
1a60: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 43  nnection.**.** C
1a70: 61 6c 6c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  all this functio
1a80: 6e 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  n with a pointer
1a90: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
1aa0: 74 68 61 74 20 77 61 73 20 70 72 65 76 69 6f 75  that was previou
1ab0: 73 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  sly.** returned 
1ac0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
1ad0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1ae0: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
1af0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1b00: 32 28 29 5d 20 61 6e 64 20 74 68 65 20 63 6f 72  2()] and the cor
1b10: 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 62  responding datab
1b20: 61 73 65 20 77 69 6c 6c 20 62 79 0a 2a 2a 20 63  ase will by.** c
1b30: 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c  losed..**.** All
1b40: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1b50: 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 5b  prepared using [
1b60: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1b70: 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
1b80: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1b90: 32 28 29 5d 20 6d 75 73 74 20 62 65 20 64 65 73  2()] must be des
1ba0: 74 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 71  troyed using [sq
1bb0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1bc0: 5d 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  ].** before this
1bd0: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
1be0: 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 53  ed. Otherwise, S
1bf0: 51 4c 49 54 45 5f 42 55 53 59 20 69 73 20 72 65  QLITE_BUSY is re
1c00: 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 0a 2a  turned and the.*
1c10: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1c20: 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 6f 70  ction remains op
1c30: 65 6e 2e 0a 2a 2a 0a 2a 2a 20 50 61 73 73 69 6e  en..**.** Passin
1c40: 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  g this routine a
1c50: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c60: 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 61 6c  tion that has al
1c70: 72 65 61 64 79 20 62 65 65 6e 0a 2a 2a 20 63 6c  ready been.** cl
1c80: 6f 73 65 64 20 72 65 73 75 6c 74 73 20 69 6e 20  osed results in 
1c90: 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1ca0: 6f 72 2e 20 20 49 66 20 6f 74 68 65 72 20 69 6e  or.  If other in
1cb0: 74 65 72 66 61 63 65 73 20 74 68 61 74 0a 2a 2a  terfaces that.**
1cc0: 20 72 65 66 65 72 65 6e 63 65 20 74 68 65 20 73   reference the s
1cd0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1ce0: 6e 65 63 74 69 6f 6e 20 61 72 65 20 70 65 6e 64  nection are pend
1cf0: 69 6e 67 20 28 65 69 74 68 65 72 20 69 6e 20 74  ing (either in t
1d00: 68 65 0a 2a 2a 20 73 61 6d 65 20 74 68 72 65 61  he.** same threa
1d10: 64 20 6f 72 20 69 6e 20 64 69 66 66 65 72 65 6e  d or in differen
1d20: 74 20 74 68 72 65 61 64 73 29 20 77 68 65 6e 20  t threads) when 
1d30: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
1d40: 63 61 6c 6c 65 64 2c 0a 2a 2a 20 74 68 65 6e 20  called,.** then 
1d50: 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1d60: 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 69 73  undefined and is
1d70: 20 61 6c 6d 6f 73 74 20 63 65 72 74 61 69 6e 6c   almost certainl
1d80: 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
1d90: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
1da0: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a  ose(sqlite3 *);.
1db0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
1dc0: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
1dd0: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
1de0: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
1df0: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
1e00: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
1e10: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
1e20: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
1e30: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
1e40: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
1e50: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
1e60: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
1e70: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
1e80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e90: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
1ea0: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
1eb0: 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ace.**.** This i
1ec0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
1ed0: 20 74 6f 20 64 6f 20 61 20 6f 6e 65 2d 74 69 6d   to do a one-tim
1ee0: 65 20 65 76 61 6c 75 61 74 61 74 69 6f 6e 20 6f  e evaluatation o
1ef0: 66 20 7a 65 72 6f 0a 2a 2a 20 6f 72 20 6d 6f 72  f zero.** or mor
1f00: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1f10: 2e 20 20 55 54 46 2d 38 20 74 65 78 74 20 6f 66  .  UTF-8 text of
1f20: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1f30: 6e 74 73 20 74 6f 0a 2a 2a 20 62 65 20 65 76 61  nts to.** be eva
1f40: 6c 75 74 65 64 20 69 73 20 70 61 73 73 65 64 20  luted is passed 
1f50: 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  in as the second
1f60: 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
1f70: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
1f80: 72 65 20 70 72 65 70 61 72 65 64 20 6f 6e 65 20  re prepared one 
1f90: 62 79 20 6f 6e 65 20 75 73 69 6e 67 20 5b 73 71  by one using [sq
1fa0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1fb0: 2c 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 75  , evaluated.** u
1fc0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
1fd0: 65 70 28 29 5d 2c 20 74 68 65 6e 20 64 65 73 74  ep()], then dest
1fe0: 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  royed using [sql
1ff0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2000: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 6e 65 20 6f  ..**.** If one o
2010: 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 51  r more of the SQ
2020: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
2030: 20 71 75 65 72 69 65 73 2c 20 74 68 65 6e 0a 2a   queries, then.*
2040: 2a 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * the callback f
2050: 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  unction specifie
2060: 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72  d by the 3rd par
2070: 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 69 6e 76  ameter is.** inv
2080: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  oked once for ea
2090: 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 71 75  ch row of the qu
20a0: 65 72 79 20 72 65 73 75 6c 74 2e 20 20 54 68 69  ery result.  Thi
20b0: 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 73 68  s callback.** sh
20c0: 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20 72 65  ould normally re
20d0: 74 75 72 6e 20 30 2e 20 20 49 66 20 74 68 65 20  turn 0.  If the 
20e0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20f0: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 76   a non-zero.** v
2100: 61 6c 75 65 20 74 68 65 6e 20 74 68 65 20 71 75  alue then the qu
2110: 65 72 79 20 69 73 20 61 62 6f 72 74 65 64 2c 20  ery is aborted, 
2120: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53  all subsequent S
2130: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2140: 20 61 72 65 20 73 6b 69 70 70 65 64 20 61 6e 64   are skipped and
2150: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
2160: 63 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  c() function ret
2170: 75 72 6e 73 20 74 68 65 20 5b 53 51 4c 49 54 45  urns the [SQLITE
2180: 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _ABORT]..**.** T
2190: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
21a0: 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61   to this interfa
21b0: 63 65 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  ce is an arbitra
21c0: 72 79 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ry pointer that 
21d0: 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
21e0: 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
21f0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61 73  back function as
2200: 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d   its first param
2210: 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eter..**.** The 
2220: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
2230: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
2240: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6e 75  nction is the nu
2250: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 6f 6c 75 6d  mber of.** colum
2260: 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
2270: 72 65 73 75 6c 74 2e 20 20 54 68 65 20 33 72 64  result.  The 3rd
2280: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2290: 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  e callback.** is
22a0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74 72   an array of str
22b0: 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65  ings holding the
22c0: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68   values for each
22d0: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 73 20 65 78   column.** as ex
22e0: 74 72 61 63 74 65 64 20 75 73 69 6e 67 20 5b 73  tracted using [s
22f0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2300: 78 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 34 74  xt()]..** The 4t
2310: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2320: 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
2330: 6e 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e  n array of strin
2340: 67 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 75  gs.** obtained u
2350: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
2360: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64  lumn_name()] and
2370: 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 74 68 65 20   holding.** the 
2380: 6e 61 6d 65 73 20 6f 66 20 65 61 63 68 20 63 6f  names of each co
2390: 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lumn..**.** The 
23a0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
23b0: 6e 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 65  n may be NULL, e
23c0: 76 65 6e 20 66 6f 72 20 71 75 65 72 69 65 73 2e  ven for queries.
23d0: 20 20 41 20 4e 55 4c 4c 0a 2a 2a 20 63 61 6c 6c    A NULL.** call
23e0: 62 61 63 6b 20 69 73 20 6e 6f 74 20 61 6e 20 65  back is not an e
23f0: 72 72 6f 72 2e 20 20 49 74 20 6a 75 73 74 20 6d  rror.  It just m
2400: 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 63 61 6c  eans that no cal
2410: 6c 62 61 63 6b 0a 2a 2a 20 77 69 6c 6c 20 62 65  lback.** will be
2420: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
2430: 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
2440: 72 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67  rs while parsing
2450: 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 74   or evaluating t
2460: 68 65 20 53 51 4c 20 28 62 75 74 0a 2a 2a 20 6e  he SQL (but.** n
2470: 6f 74 20 77 68 69 6c 65 20 65 78 65 63 75 74 69  ot while executi
2480: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 29  ng the callback)
2490: 20 74 68 65 6e 20 61 6e 20 61 70 70 72 6f 70 72   then an appropr
24a0: 69 61 74 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65  iate error.** me
24b0: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
24c0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
24d0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
24e0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
24f0: 64 0a 2a 2a 20 2a 65 72 72 6d 73 67 20 69 73 20  d.** *errmsg is 
2500: 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2510: 20 74 68 61 74 20 6d 65 73 73 61 67 65 2e 20 20   that message.  
2520: 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
2530: 74 69 6f 6e 0a 2a 2a 20 69 73 20 72 65 73 70 6f  tion.** is respo
2540: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
2550: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 75 73  ng the memory us
2560: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
2570: 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 65 72 72 6d  e()]..** If errm
2580: 73 67 3d 3d 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e  sg==NULL, then n
2590: 6f 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  o error message 
25a0: 69 73 20 65 76 65 72 20 77 72 69 74 74 65 6e 2e  is ever written.
25b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  .**.** The retur
25c0: 6e 20 76 61 6c 75 65 20 69 73 20 69 73 20 53 51  n value is is SQ
25d0: 4c 49 54 45 5f 4f 4b 20 69 66 20 74 68 65 72 65  LITE_OK if there
25e0: 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 20 61   are no errors a
25f0: 6e 64 0a 2a 2a 20 73 6f 6d 65 20 6f 74 68 65 72  nd.** some other
2600: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
2610: 74 75 72 6e 20 63 6f 64 65 5d 20 69 66 20 74 68  turn code] if th
2620: 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  ere is an error.
2630: 20 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63    .** The partic
2640: 75 6c 61 72 20 72 65 74 75 72 6e 20 76 61 6c 75  ular return valu
2650: 65 20 64 65 70 65 6e 64 73 20 6f 6e 20 74 68 65  e depends on the
2660: 20 74 79 70 65 20 6f 66 20 65 72 72 6f 72 2e 20   type of error. 
2670: 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  .**.*/.int sqlit
2680: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
2690: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
26a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26b0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
26c0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
26d0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
26e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
2700: 20 74 6f 20 62 65 20 65 76 61 6c 75 74 65 64 20   to be evaluted 
2710: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
2720: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
2730: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
2740: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
2750: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
2760: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2770: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2780: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
2790: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
27a0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
27b0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
27c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27d0: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
27e0: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
27f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2800: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
2810: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
2820: 54 45 5f 4f 4b 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  TE_OK.**.** Many
2830: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
2840: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
2850: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
2860: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
2870: 77 6e 0a 2a 2a 20 61 62 6f 76 65 20 69 6e 20 6f  wn.** above in o
2880: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
2890: 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  s success or fai
28a0: 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lure..**.** The 
28b0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 62 6f  result codes abo
28c0: 76 65 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ve are the only 
28d0: 6f 6e 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  ones returned by
28e0: 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 0a 2a   SQLite in its.*
28f0: 2a 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  * default config
2900: 75 72 61 74 69 6f 6e 2e 20 20 48 6f 77 65 76 65  uration.  Howeve
2910: 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  r, the [sqlite3_
2920: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
2930: 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 41 50 49 20  codes()].** API 
2940: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73  can be used to s
2950: 65 74 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  et a database co
2960: 6e 6e 65 63 74 6f 69 6e 20 74 6f 20 72 65 74 75  nnectoin to retu
2970: 72 6e 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  rn more detailed
2980: 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 64 65 73  .** result codes
2990: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
29a0: 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  : [SQLITE_IOERR_
29b0: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
29c0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2a  result codes].**
29d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
29e0: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
29f0: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
2a00: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
2a10: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
2a20: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
2a30: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
2a40: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
2a50: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
2a60: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
2a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2a80: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
2a90: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 49 6e 74 65  * NOT USED. Inte
2aa0: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
2ab0: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
2ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
2ad0: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
2ae0: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
2af0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
2b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
2b10: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
2b20: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
2b30: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
2b40: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
2b50: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
2b60: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
2b70: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
2b80: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
2b90: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
2ba0: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
2bb0: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
2bc0: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
2bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2be0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
2bf0: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
2c00: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
2c10: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
2c20: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
2c30: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
2c40: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
2c50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2c60: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
2c70: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
2c80: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
2c90: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
2ca0: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ()*/.#define SQL
2cb0: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
2cc0: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
2cd0: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
2ce0: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
2cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
2d00: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
2d10: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
2d20: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
2d30: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
2d40: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
2d50: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f  ND    12   /* NO
2d60: 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72  T USED. Table or
2d70: 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e   record not foun
2d80: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
2d90: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
2da0: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
2db0: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
2dc0: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
2dd0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
2de0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
2df0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
2e00: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
2e10: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
2e20: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
2e30: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e  COL    15   /* N
2e40: 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 73  OT USED. Databas
2e50: 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20  e lock protocol 
2e60: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
2e70: 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20   SQLITE_EMPTY   
2e80: 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61      16   /* Data
2e90: 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f  base is empty */
2ea0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2eb0: 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20  SCHEMA      17  
2ec0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
2ed0: 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20   schema changed 
2ee0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2ef0: 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38  E_TOOBIG      18
2f00: 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20     /* String or 
2f10: 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a  BLOB exceeds siz
2f20: 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69  e limit */.#defi
2f30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
2f40: 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62  AINT  19   /* Ab
2f50: 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 74 72  ort due to contr
2f60: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
2f70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2f80: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
2f90: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
2fa0: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
2fb0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
2fc0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
2fd0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
2fe0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
2ff0: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
3000: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
3010: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
3020: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
3030: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
3040: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
3050: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
3060: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
3070: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3080: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
3090: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
30a0: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
30b0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
30c0: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
30d0: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
30e0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
30f0: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
3100: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
3110: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
3120: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
3130: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
3140: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
3150: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
3160: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
3170: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
3180: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
3190: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
31a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
31b0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
31c0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
31d0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
31e0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
31f0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
3200: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
3210: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
3220: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
3230: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
3240: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
3250: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
3260: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
3270: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a   of 26 integer.*
3280: 2a 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 64  * result codes d
3290: 65 73 63 72 69 62 65 64 20 61 74 20 72 65 73 75  escribed at resu
32a0: 6c 74 2d 63 6f 64 65 73 2e 20 20 48 6f 77 65 76  lt-codes.  Howev
32b0: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
32c0: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a 2a  as shown that.**
32d0: 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72   many of these r
32e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
32f0: 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61 69 6e  too course-grain
3300: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
3310: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
3320: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
3330: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
3340: 73 20 75 73 65 72 73 20 6d 69 67 68 74 20 6c 69  s users might li
3350: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
3360: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
3370: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
3380: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
3390: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
33a0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
33b0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
33c0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
33d0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
33e0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
33f0: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
3400: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
3410: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
3420: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65  sult codes are e
3430: 6e 61 62 6c 65 64 20 28 6f 72 20 64 69 73 61 62  nabled (or disab
3440: 6c 65 64 29 20 66 6f 72 20 0a 2a 2a 20 65 61 63  led) for .** eac
3450: 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  h database.** co
3460: 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74  nnection using t
3470: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  he [sqlite3_exte
3480: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
3490: 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a  s()] API..** .**
34a0: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
34b0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
34c0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
34d0: 20 6c 69 73 74 65 64 20 61 62 6f 76 65 2e 0a 2a   listed above..*
34e0: 2a 20 57 65 20 65 78 70 65 63 74 20 74 68 65 20  * We expect the 
34f0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
3500: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3510: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
3520: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
3530: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
3540: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
3550: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
3560: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
3570: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
3580: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
3590: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
35a0: 20 0a 2a 2a 20 54 68 65 20 73 79 6d 62 6f 6c 69   .** The symboli
35b0: 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78  c name for an ex
35c0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
35d0: 64 65 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69  de always contai
35e0: 6e 73 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  ns a related.** 
35f0: 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  primary result c
3600: 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78 2e  ode as a prefix.
3610: 20 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74    Primary result
3620: 20 63 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20 61   codes contain a
3630: 20 73 69 6e 67 6c 65 0a 2a 2a 20 22 5f 22 20 63   single.** "_" c
3640: 68 61 72 61 63 74 65 72 2e 20 20 45 78 74 65 6e  haracter.  Exten
3650: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
3660: 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20   contain two or 
3670: 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63 74  more "_" charact
3680: 65 72 73 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d 65  ers..** The nume
3690: 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  ric value of an 
36a0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
36b0: 63 6f 64 65 20 63 61 6e 20 62 65 20 63 6f 6e 76  code can be conv
36c0: 65 72 74 65 64 20 74 6f 20 69 74 73 0a 2a 2a 20  erted to its.** 
36d0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72  corresponding pr
36e0: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
36f0: 65 20 62 79 20 6d 61 73 6b 69 6e 67 20 6f 66 66  e by masking off
3700: 20 74 68 65 20 6c 6f 77 65 72 20 38 20 62 79 74   the lower 8 byt
3710: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  es..**.** The SQ
3720: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63  LITE_OK result c
3730: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  ode will never b
3740: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20  e extended.  It 
3750: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62  will always.** b
3760: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a  e exactly zero..
3770: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3780: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20  E_IOERR_READ    
3790: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
37a0: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
37b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
37c0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
37d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
37e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
37f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
3800: 49 54 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  ITE         (SQL
3810: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
3820: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3830: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
3840: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3850: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OERR | (4<<8)).#
3860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3870: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20  ERR_DIR_FSYNC   
3880: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3890: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
38a0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
38b0: 52 55 4e 43 41 54 45 20 20 20 20 20 20 28 53 51  RUNCATE      (SQ
38c0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
38d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
38e0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
38f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
3900: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
3910: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3920: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
3930: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
3940: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
3950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
3960: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53  RDLOCK        (S
3970: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
3980: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
3990: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
39a0: 45 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  E        (SQLITE
39b0: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
39c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
39d0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
39e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
39f0: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 0a 2f  RR | (11<<8))../
3a00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
3a10: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
3a20: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
3a30: 0a 2a 2a 20 43 6f 6d 62 69 6e 61 74 69 6f 6e 20  .** Combination 
3a40: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
3a50: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
3a60: 75 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 74  used as the.** t
3a70: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
3a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
3a90: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
3aa0: 63 65 20 61 6e 64 0a 2a 2a 20 61 73 20 66 6f 75  ce and.** as fou
3ab0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
3ac0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
3ad0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
3ae0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
3af0: 0a 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  .**.*/.#define S
3b00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
3b10: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
3b20: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
3b30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
3b40: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
3b50: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
3b60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
3b70: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
3b80: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
3b90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
3ba0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
3bb0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
3bc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
3bd0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
3be0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
3bf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
3c00: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
3c10: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
3c20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
3c30: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
3c40: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
3c50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
3c60: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
3c70: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
3c80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
3c90: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
3ca0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
3cb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
3cc0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
3cd0: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
3ce0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
3cf0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
3d00: 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53  002000.#define S
3d10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
3d20: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
3d30: 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  004000../*.** CA
3d40: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
3d50: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
3d60: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
3d70: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
3d80: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
3d90: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
3da0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
3db0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
3dc0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
3dd0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a  f the following.
3de0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
3df0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
3e00: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
3e10: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
3e20: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
3e30: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
3e40: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
3e50: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
3e60: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
3e70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
3e80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
3e90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
3ea0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
3eb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
3ec0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
3ed0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
3ee0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
3ef0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
3f00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
3f10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
3f20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
3f30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
3f40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
3f50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
3f60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
3f70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
3f80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
3f90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
3fa0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
3fb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
3fc0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
3fd0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
3fe0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
3ff0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
4000: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
4010: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
4020: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
4030: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4040: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
4050: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
4060: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
4070: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
4080: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
4090: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
40a0: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
40b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
40c0: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
40d0: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
40e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
40f0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
4100: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
4110: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4120: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
4130: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
4140: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4150: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
4160: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
4170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4180: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
4190: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
41a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
41b0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
41c0: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
41d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
41e0: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
41f0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
4200: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4210: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
4220: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
4230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4240: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
4250: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
4260: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4270: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
4280: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
4290: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
42a0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
42b0: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
42c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
42d0: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
42e0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
42f0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
4300: 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 76  lowing integer v
4310: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
4320: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
4330: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
4340: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
4350: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
4360: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
4370: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
4380: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
4390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
43a0: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
43b0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
43c0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
43d0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
43e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
43f0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
4400: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
4410: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
4420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4430: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
4440: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
4450: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
4460: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a  tion Type Flags.
4470: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
4480: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
4490: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
44a0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
44b0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
44c0: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
44d0: 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66  ination of the f
44e0: 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
44f0: 20 76 61 6c 75 65 73 20 61 73 0a 2a 2a 20 74 68   values as.** th
4500: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
4510: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
4520: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
4530: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
4540: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
4550: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
4560: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
4570: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
4580: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
4590: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
45a0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
45b0: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 20 54  t be flushed.  T
45c0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
45d0: 4f 52 4d 41 4c 20 6d 65 61 6e 73 20 0a 2a 2a 20  ORMAL means .** 
45e0: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
45f0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
4600: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e    The SQLITE_SYN
4610: 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e  C_FULL flag mean
4620: 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  s .** to use Mac
4630: 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS-X style full
4640: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
4650: 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66  fsync()..*/.#def
4660: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
4670: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
4680: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
4690: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
46a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
46c0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
46d0: 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a 2a    0x00010.../*.*
46e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
46f0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
4700: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
4710: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
4720: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
4730: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
4740: 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e   in the OS.** in
4750: 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20  terface layer.  
4760: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
4770: 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e  terface implemen
4780: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
4790: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
47a0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
47b0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
47c0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
47d0: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
47e0: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
47f0: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
4800: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
4810: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
4820: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
4830: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
4840: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
4850: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
4860: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
4870: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
4880: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
4890: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
48a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
48b0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
48c0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
48d0: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
48e0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
48f0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
4900: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
4910: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
4920: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
4930: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
4940: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
4950: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
4960: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
4970: 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73 20  method contains 
4980: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
4990: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
49a0: 68 65 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20  he this object. 
49b0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
49c0: 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74 68  ines the.** meth
49d0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
49e0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
49f0: 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20 74  ations against t
4a00: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a  he open file..**
4a10: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
4a20: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
4a30: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
4a40: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
4a50: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
4a60: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
4a70: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
4a80: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
4a90: 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65 63  nc()..*  The sec
4aa0: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 6e  ond choice is an
4ab0: 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20 66  .** OS-X style f
4ac0: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53 51  ullsync.  The SQ
4ad0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66  LITE_SYNC_DATA f
4ae0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
4af0: 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61 74  in to.** indicat
4b00: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
4b10: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
4b20: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
4b30: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a 2a  de needs to be.*
4b40: 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a 2a  * synced..** .**
4b50: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
4b60: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
4b70: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
4b80: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
4b90: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
4ba0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
4bb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
4bc0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
4bd0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
4be0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
4bf0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
4c00: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
4c10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
4c20: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
4c30: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
4c40: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
4c50: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
4c60: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
4c70: 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68 65  k.  .** The xChe
4c80: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
4c90: 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a   method looks.**
4ca0: 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20 64   to see if any d
4cb0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4cc0: 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74 68  on, either in th
4cd0: 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72  is.** process or
4ce0: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
4cf0: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
4d00: 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c 0a  ng an RESERVED,.
4d10: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
4d20: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
4d30: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
4d40: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
4d50: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
4d60: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 69  ists and false i
4d70: 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  f not..** .** Th
4d80: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
4d90: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
4da0: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
4db0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
4dc0: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
4dd0: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
4de0: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
4df0: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
4e00: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4e10: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
4e20: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
4e30: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
4e40: 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e  ment.** is an in
4e50: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 20  teger opcode.   
4e60: 54 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  The third.** arg
4e70: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
4e80: 69 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ic pointer which
4e90: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
4ea0: 62 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  be a pointer.** 
4eb0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
4ec0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
4ed0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
4ee0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
4ef0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
4f00: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
4f10: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
4f20: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
4f30: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
4f40: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
4f50: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
4f60: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
4f70: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
4f80: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
4f90: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
4fa0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
4fb0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
4fc0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
4fd0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
4fe0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
4ff0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
5000: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 6f   core reserves o
5010: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
5020: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
5030: 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51 4c   use. .** A [SQL
5040: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
5050: 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  ATE | list of op
5060: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
5070: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
5080: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
5090: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
50a0: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
50b0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
50c0: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20 0a  ld use opcodes .
50d0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
50e0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
50f0: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  flicts..**.** Th
5100: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
5110: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
5120: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
5130: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
5140: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
5150: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
5160: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
5170: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
5180: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
5190: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
51a0: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
51b0: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
51c0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
51d0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
51e0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
51f0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
5200: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
5210: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
5220: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
5230: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
5240: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5250: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
5260: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
5270: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
5280: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5290: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
52a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
52b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
52c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
52d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
52e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
52f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
5300: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5310: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
5320: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5330: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
5340: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5350: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
5360: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5370: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
5380: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
5390: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
53a0: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
53b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
53c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
53d0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
53e0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
53f0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
5400: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5420: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
5430: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
5440: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
5450: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
5460: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
5470: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
5480: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
5490: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
54a0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
54b0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
54c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
54d0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
54e0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
54f0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
5500: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
5510: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
5520: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
5530: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
5540: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
5550: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
5560: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
5570: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5580: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
5590: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
55a0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
55b0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
55c0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
55d0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
55e0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
55f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
5600: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5610: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
5620: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
5630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5640: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
5650: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
5660: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
5670: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
5680: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
5690: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
56a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
56b0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
56c0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
56d0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
56e0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
56f0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
5700: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
5710: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
5720: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
5730: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
5740: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
5750: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
5760: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
5770: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
5780: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
5790: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
57a0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
57b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
57c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
57d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
57e0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
57f0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
5800: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
5810: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  *);.  int (*xFil
5820: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
5830: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
5840: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
5850: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
5860: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
5870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
5880: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
5890: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
58a0: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
58b0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
58c0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
58d0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
58e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
58f0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
5900: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
5910: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
5920: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
5930: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
5940: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
5950: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
5960: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5970: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
5980: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5990: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
59a0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
59b0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
59c0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
59d0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
59e0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
59f0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
5a00: 61 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  ases the xFileCo
5a10: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
5a20: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
5a30: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
5a40: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
5a50: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5a60: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
5a70: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
5a80: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
5a90: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
5aa0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
5ab0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
5ac0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
5ad0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
5ae0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
5af0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 20 54 68 69   points to.  Thi
5b00: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
5b10: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
5b20: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
5b30: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
5b40: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
5b50: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
5b60: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
5b70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
5b80: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
5b90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5ba0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
5bb0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
5bc0: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
5bd0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
5be0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
5bf0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
5c00: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
5c10: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
5c20: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
5c30: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
5c40: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
5c50: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
5c60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
5c70: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
5c80: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
5c90: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5ca0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
5cb0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
5cc0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
5cd0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
5ce0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
5cf0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
5d00: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
5d10: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
5d20: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
5d30: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
5d40: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
5d50: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
5d60: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
5d70: 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a  ce between the.*
5d80: 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  * SQLite core an
5d90: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
5da0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
5db0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
5dc0: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
5dd0: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
5de0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
5df0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
5e00: 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20  ** The iVersion 
5e10: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
5e20: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
5e30: 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74 75 72  larger for futur
5e40: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
5e50: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
5e60: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
5e70: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
5e80: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
5e90: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
5ea0: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
5eb0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
5ec0: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
5ed0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
5ee0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
5ef0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
5f00: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
5f10: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
5f20: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
5f30: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
5f40: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
5f50: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
5f60: 65 67 69 73 74 65 72 65 64 20 76 66 73 20 6d 6f  egistered vfs mo
5f70: 64 75 6c 65 73 20 61 72 65 20 6b 65 70 74 20 6f  dules are kept o
5f80: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
5f90: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
5fa0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
5fb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
5fc0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
5fd0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
5fe0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
5ff0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
6000: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
6010: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
6020: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
6030: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
6040: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
6050: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 0a 2a  ches the list..*
6060: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
6070: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
6080: 20 66 69 65 6c 64 73 20 69 6e 20 74 68 65 20 73   fields in the s
6090: 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20 73  qlite3_vfs .** s
60a0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
60b0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
60c0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
60d0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
60e0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
60f0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
6100: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
6110: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
6120: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
6130: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
6140: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
6150: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
6160: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
6170: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
6180: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
6190: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
61a0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
61b0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
61c0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
61d0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
61e0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
61f0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
6200: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  s..**.** SQLite 
6210: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
6220: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
6230: 65 20 73 74 72 69 6e 67 20 70 61 73 73 65 64 20  e string passed 
6240: 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20 69 73  to.** xOpen() is
6250: 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61 6d 65   a full pathname
6260: 20 61 73 20 67 65 6e 65 72 61 74 65 64 20 62 79   as generated by
6270: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
6280: 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74 68 65   and.** that the
6290: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
62a0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
62b0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
62c0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
62d0: 20 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65    So the [sqlite
62e0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72  3_file] can stor
62f0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
6300: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
6310: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
6320: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
6330: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
6340: 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  son..**.** The f
6350: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6360: 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20 63 6f   xOpen() is a co
6370: 70 79 20 6f 66 20 74 68 65 20 66 6c 61 67 73 20  py of the flags 
6380: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
6390: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
63a0: 29 5d 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33  )].  If [sqlite3
63b0: 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c  _open()] or [sql
63c0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 0a 2a  ite3_open16()].*
63d0: 2a 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  * is used, then 
63e0: 66 6c 61 67 73 20 69 73 20 5b 53 51 4c 49 54 45  flags is [SQLITE
63f0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
6400: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
6410: 43 52 45 41 54 45 5d 2e 0a 2a 2a 20 49 66 20 78  CREATE]..** If x
6420: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
6430: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
6440: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
6450: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
6460: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
6470: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
6480: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
6490: 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20  Flags may be.** 
64a0: 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69  set..** .** SQLi
64b0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
64c0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
64d0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
64e0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
64f0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
6500: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
6510: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a 2a 2a  g opened:.** .**
6520: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
6530: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
6540: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
6550: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6560: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
6570: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
6580: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
6590: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
65a0: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
65b0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
65c0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
65d0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
65e0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
65f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
6600: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
6610: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  OURNAL].** </ul>
6620: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
6630: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
6640: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
6650: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
6660: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74   to.** changes t
6670: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
6680: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
6690: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
66a0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
66b0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
66c0: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
66d0: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 2c  ery or rollback,
66e0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
66f0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
6700: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
6710: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
6720: 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72 65 0a 2a  is journal are.*
6730: 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e 20  * also a no-op. 
6740: 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
6750: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
6760: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 49   return SQLITE_I
6770: 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 68 65 20  OERR..** Or the 
6780: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
6790: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
67a0: 68 65 20 61 20 64 61 74 61 62 61 73 65 20 66 69  he a database fi
67b0: 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 64 6f  le will.** be do
67c0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
67d0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
67e0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
67f0: 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20 61 6e  ndom order.** an
6800: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
6810: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
6820: 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53  dingly..** .** S
6830: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
6840: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
6850: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
6860: 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
6870: 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  method:.** .** <
6880: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
6890: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
68a0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
68b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
68c0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
68d0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  .** .** The [SQL
68e0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
68f0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
6900: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
6910: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
6920: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
6930: 65 64 2e 20 20 54 68 69 73 20 77 69 6c 6c 20 61  ed.  This will a
6940: 6c 77 61 79 73 20 62 65 20 73 65 74 20 66 6f 72  lways be set for
6950: 20 54 45 4d 50 20 0a 2a 2a 20 64 61 74 61 62 61   TEMP .** databa
6960: 73 65 73 20 61 6e 64 20 6a 6f 75 72 6e 61 6c 73  ses and journals
6970: 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72   and for subjour
6980: 6e 61 6c 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b  nals.  The .** [
6990: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
69a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e  USIVE] flag mean
69b0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
69c0: 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66  d be opened.** f
69d0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
69e0: 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20  ess.  This flag 
69f0: 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66  is set for all f
6a00: 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66  iles except.** f
6a10: 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
6a20: 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 0a 2a  base file..** .*
6a30: 2a 20 53 70 61 63 65 20 74 6f 20 68 6f 6c 64 20  * Space to hold 
6a40: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
6a50: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
6a60: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
6a70: 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  d .** argument t
6a80: 6f 20 78 4f 70 65 6e 20 69 73 20 61 6c 6c 6f 63  o xOpen is alloc
6a90: 61 74 65 64 20 62 79 20 63 61 6c 6c 65 72 20 28  ated by caller (
6aa0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 29  the SQLite core)
6ab0: 2e 20 0a 2a 2a 20 73 7a 4f 73 46 69 6c 65 20 62  . .** szOsFile b
6ac0: 79 74 65 73 20 61 72 65 20 61 6c 6c 6f 63 61 74  ytes are allocat
6ad0: 65 64 20 66 6f 72 20 74 68 69 73 20 6f 62 6a 65  ed for this obje
6ae0: 63 74 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  ct.  The xOpen m
6af0: 65 74 68 6f 64 0a 2a 2a 20 66 69 6c 6c 73 20 69  ethod.** fills i
6b00: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
6b10: 73 70 61 63 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  space..** .** Th
6b20: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
6b30: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
6b40: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
6b50: 45 53 53 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20  ESS_EXISTS] .** 
6b60: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
6b70: 65 78 69 73 74 61 6e 63 65 20 6f 66 20 61 20 66  existance of a f
6b80: 69 6c 65 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  ile,.** or [SQLI
6b90: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
6ba0: 49 54 45 5d 20 74 6f 20 74 65 73 74 20 74 6f 20  ITE] to test to 
6bb0: 73 65 65 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65  see.** if a file
6bc0: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
6bd0: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
6be0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
6bf0: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f  D].** to test to
6c00: 20 73 65 65 20 69 66 20 61 20 66 69 6c 65 20 69   see if a file i
6c10: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
6c20: 62 6c 65 2e 20 20 54 68 65 20 66 69 6c 65 20 63  ble.  The file c
6c30: 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69 72 65  an be a .** dire
6c40: 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51  ctory..** .** SQ
6c50: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
6c60: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
6c70: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
6c80: 62 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  byte for.** the 
6c90: 6f 75 74 70 75 74 20 62 75 66 66 65 72 73 20 66  output buffers f
6ca0: 6f 72 20 78 47 65 74 54 65 6d 70 6e 61 6d 65 20  or xGetTempname 
6cb0: 61 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  and xFullPathnam
6cc0: 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52  e..** .** The xR
6cd0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
6ce0: 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72  eep(), and xCurr
6cf0: 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66  entTime() interf
6d00: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
6d10: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
6d20: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
6d30: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
6d40: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
6d50: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
6d60: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
6d70: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
6d80: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
6d90: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
6da0: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
6db0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
6dc0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
6dd0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
6de0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
6df0: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
6e00: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
6e10: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
6e20: 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c  ned.  The.** xSl
6e30: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
6e40: 73 65 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  se the calling t
6e50: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
6e60: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
6e70: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
6e80: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
6e90: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
6ea0: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
6eb0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
6ec0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
6ed0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
6ee0: 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a  and.** time..*/.
6ef0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
6f00: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
6f10: 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73  e3_vfs;.struct s
6f20: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
6f30: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
6f40: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
6f50: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
6f60: 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f  ber */.  int szO
6f70: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
6f80: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
6f90: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
6fa0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
6fb0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
6fc0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
6fd0: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
6fe0: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
6ff0: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
7000: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
7010: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
7020: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
7030: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
7040: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
7050: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
7060: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
7070: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
7080: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
7090: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
70a0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
70b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
70c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
70d0: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
70e0: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
70f0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
7100: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
7110: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
7120: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
7130: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
7140: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
7150: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
7160: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
7170: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
7180: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
7190: 20 28 2a 78 47 65 74 54 65 6d 70 6e 61 6d 65 29   (*xGetTempname)
71a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
71b0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
71c0: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
71d0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
71e0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
71f0: 6d 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  me, char *zOut);
7200: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
7210: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
7220: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
7230: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
7240: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
7250: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
7260: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
7270: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Msg);.  void *(*
7280: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
7290: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
72a0: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
72b0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
72c0: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
72d0: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
72e0: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
72f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
7300: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
7310: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
7320: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
7330: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
7340: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
7350: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
7360: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
7370: 65 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69  e*);.  /* New fi
7380: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
7390: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
73a0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
73b0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
73c0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
73d0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
73e0: 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f  appens. */.};../
73f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
7400: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
7410: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
7420: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
7430: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
7440: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
7450: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
7460: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
7470: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
7480: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
7490: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
74a0: 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 6b 69 6e  rmine.** the kin
74b0: 64 20 6f 66 20 77 68 61 74 20 6b 69 6e 64 20 6f  d of what kind o
74c0: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
74d0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
74e0: 20 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66   is.** looking f
74f0: 6f 72 2e 20 20 57 69 74 68 20 53 51 4c 49 54 45  or.  With SQLITE
7500: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
7510: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
7520: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
7530: 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68  cks to see if th
7540: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 20 20  e file exists.  
7550: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
7560: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 0a 2a 2a  SS_READWRITE,.**
7570: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
7580: 68 6f 64 20 63 68 65 63 6b 73 20 74 6f 20 73 65  hod checks to se
7590: 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  e if the file is
75a0: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 0a 2a   both readable.*
75b0: 2a 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 20  * and writable. 
75c0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
75d0: 45 53 53 5f 52 45 41 44 20 74 68 65 20 78 41 63  ESS_READ the xAc
75e0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
75f0: 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20  hecks to see if 
7600: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
7610: 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  able..*/.#define
7620: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
7630: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
7640: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
7650: 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65  _READWRITE 1.#de
7660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
7670: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a  SS_READ      2..
7680: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7690: 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
76a0: 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
76b0: 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  t Codes.**.** Th
76c0: 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
76d0: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
76e0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  he.** [SQLITE_IO
76f0: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
7700: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
7710: 5d 20 66 65 61 74 75 72 65 2e 0a 2a 2a 20 42 79  ] feature..** By
7720: 20 64 65 66 61 75 6c 74 2c 20 53 51 4c 69 74 65   default, SQLite
7730: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
7740: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 6f 6e 6c 79  turn one of only
7750: 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   26 integer.** [
7760: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
7770: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 57 68 65 6e  lt codes].  When
7780: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
7790: 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20 65 6e   codes.** are en
77a0: 61 62 6c 65 64 20 62 79 20 74 68 69 73 20 72 6f  abled by this ro
77b0: 75 74 69 6e 65 2c 20 74 68 65 20 72 65 70 65 74  utine, the repet
77c0: 6f 69 72 65 20 6f 66 20 72 65 73 75 6c 74 20 63  oire of result c
77d0: 6f 64 65 73 20 63 61 6e 20 62 65 0a 2a 2a 20 6d  odes can be.** m
77e0: 75 63 68 20 6c 61 72 67 65 72 20 61 6e 64 20 63  uch larger and c
77f0: 61 6e 20 28 68 6f 70 65 66 75 6c 6c 79 29 20 70  an (hopefully) p
7800: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
7810: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
7820: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 63 61  .** about the ca
7830: 75 73 65 20 6f 66 20 61 6e 20 65 72 72 6f 72 2e  use of an error.
7840: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
7850: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7860: 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65 20 74 68  boolean value th
7870: 61 74 20 74 75 72 6e 73 20 65 78 74 65 6e 64 65  at turns extende
7880: 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
7890: 73 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 20 20 45  s on and off.  E
78a0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
78b0: 6f 64 65 73 20 61 72 65 20 6f 66 66 20 62 79 20  odes are off by 
78c0: 64 65 66 61 75 6c 74 20 66 6f 72 0a 2a 2a 20 62  default for.** b
78d0: 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
78e0: 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
78f0: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
7900: 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
7910: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
7920: 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
7930: 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
7940: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7950: 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
7960: 77 69 64 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65  wid.**.** Each e
7970: 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74  ntry in an SQLit
7980: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e  e table has a un
7990: 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
79a0: 65 64 20 69 6e 74 65 67 65 72 20 6b 65 79 0a 2a  ed integer key.*
79b0: 2a 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f  * called the "ro
79c0: 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20  wid". The rowid 
79d0: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
79e0: 62 6c 65 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  ble as an undecl
79f0: 61 72 65 64 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e  ared.** column n
7a00: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
7a10: 20 6f 72 20 5f 52 4f 57 49 44 5f 2e 20 20 49 66   or _ROWID_.  If
7a20: 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
7a30: 20 63 6f 6c 75 6d 6e 20 6f 66 0a 2a 2a 20 74 79   column of.** ty
7a40: 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  pe INTEGER PRIMA
7a50: 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74  RY KEY then that
7a60: 20 63 6f 6c 75 6d 6e 20 69 73 20 61 6e 6f 74 68   column is anoth
7a70: 65 72 20 61 6e 20 61 6c 69 61 73 20 66 6f 72 20  er an alias for 
7a80: 74 68 65 0a 2a 2a 20 72 6f 77 69 64 2e 0a 2a 2a  the.** rowid..**
7a90: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
7aa0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77   returns the row
7ab0: 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  id of the most r
7ac0: 65 63 65 6e 74 20 49 4e 53 45 52 54 20 69 6e 74  ecent INSERT int
7ad0: 6f 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  o.** the databas
7ae0: 65 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62  e from the datab
7af0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 67  ase connection g
7b00: 69 76 65 6e 20 69 6e 20 74 68 65 20 66 69 72 73  iven in the firs
7b10: 74 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  t .** argument. 
7b20: 20 49 66 20 6e 6f 20 69 6e 73 65 72 74 73 20 68   If no inserts h
7b30: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
7b40: 64 20 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61  d on this databa
7b50: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
7b60: 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
7b70: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
7b80: 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77 69  INSERT occurs wi
7b90: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
7ba0: 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f  then the rowid o
7bb0: 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65  f the.** inserte
7bc0: 64 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65  d row is returne
7bd0: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
7be0: 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  e as long as the
7bf0: 20 74 72 69 67 67 65 72 0a 2a 2a 20 69 73 20 72   trigger.** is r
7c00: 75 6e 6e 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63  unning.  But onc
7c10: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
7c20: 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
7c30: 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
7c40: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
7c50: 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
7c60: 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
7c70: 65 64 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a  ed before the.**
7c80: 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a   trigger fired..
7c90: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
7ca0: 20 74 68 72 65 61 64 20 64 6f 65 73 20 61 20 6e   thread does a n
7cb0: 65 77 20 69 6e 73 65 72 74 20 6f 6e 20 74 68 65  ew insert on the
7cc0: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
7cd0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
7ce0: 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
7cf0: 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
7d00: 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
7d10: 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69  last insert rowi
7d20: 64 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  d,.** then the r
7d30: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
7d40: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
7d50: 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 73 71 6c  ndefined..*/.sql
7d60: 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
7d70: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
7d80: 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
7d90: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7da0: 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
7db0: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
7dc0: 65 64 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  ed.**.** This fu
7dd0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
7de0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
7df0: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
7e00: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
7e10: 28 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20  (or inserted or 
7e20: 64 65 6c 65 74 65 64 29 20 62 79 20 74 68 65 20  deleted) by the 
7e30: 6d 6f 73 74 20 72 65 63 65 6e 74 20 53 51 4c 20  most recent SQL 
7e40: 73 74 61 74 65 6d 65 6e 74 2e 20 20 4f 6e 6c 79  statement.  Only
7e50: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68 61 74  .** changes that
7e60: 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
7e70: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49  ecified by the I
7e80: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
7e90: 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74  r.** DELETE stat
7ea0: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
7eb0: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
7ec0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
7ed0: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
7ee0: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 55 73  not counted.  Us
7ef0: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
7f00: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
7f10: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66  function.** to f
7f20: 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
7f30: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
7f40: 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
7f50: 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
7f60: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 57 69 74 68  gers..**.** With
7f70: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
7f80: 20 74 72 69 67 67 65 72 2c 20 74 68 65 20 73 71   trigger, the sq
7f90: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
7fa0: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
7fb0: 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 6f 20 66 69  .** called to fi
7fc0: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
7fd0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
7fe0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
7ff0: 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
8000: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
8010: 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
8020: 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
8030: 79 20 6f 66 20 74 68 65 20 74 72 69 67 67 65 72  y of the trigger
8040: 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 63 68 61 6e  ..**.** All chan
8050: 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2c  ges are counted,
8060: 20 65 76 65 6e 20 69 66 20 74 68 65 79 20 77 65   even if they we
8070: 72 65 20 6c 61 74 65 72 20 75 6e 64 6f 6e 65 20  re later undone 
8080: 62 79 20 61 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b  by a.** ROLLBACK
8090: 20 6f 72 20 41 42 4f 52 54 2e 20 20 45 78 63 65   or ABORT.  Exce
80a0: 70 74 2c 20 63 68 61 6e 67 65 73 20 61 73 73 6f  pt, changes asso
80b0: 63 69 61 74 65 64 20 77 69 74 68 20 63 72 65 61  ciated with crea
80c0: 74 69 6e 67 20 61 6e 64 0a 2a 2a 20 64 72 6f 70  ting and.** drop
80d0: 70 69 6e 67 20 74 61 62 6c 65 73 20 61 72 65 20  ping tables are 
80e0: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  not counted..**.
80f0: 2a 2a 20 49 66 20 61 20 63 61 6c 6c 62 61 63 6b  ** If a callback
8100: 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
8110: 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
8120: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
8130: 63 75 72 73 69 76 65 6c 79 2c 0a 2a 2a 20 74 68  cursively,.** th
8140: 65 6e 20 74 68 65 20 63 68 61 6e 67 65 73 20 69  en the changes i
8150: 6e 20 74 68 65 20 69 6e 6e 65 72 2c 20 72 65 63  n the inner, rec
8160: 75 72 73 69 76 65 20 63 61 6c 6c 20 61 72 65 20  ursive call are 
8170: 63 6f 75 6e 74 65 64 20 74 6f 67 65 74 68 65 72  counted together
8180: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 63 68 61  .** with the cha
8190: 6e 67 65 73 20 69 6e 20 74 68 65 20 6f 75 74 65  nges in the oute
81a0: 72 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 53 51  r call..**.** SQ
81b0: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
81c0: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
81d0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
81e0: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
81f0: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
8200: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
8210: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
8220: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
8230: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
8240: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
8250: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
8260: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
8270: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
8280: 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69  ecause of.** thi
8290: 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  s optimization, 
82a0: 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74  the change count
82b0: 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f   for "DELETE FRO
82c0: 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65  M table" will be
82d0: 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c  .** zero regardl
82e0: 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ess of the numbe
82f0: 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68  r of elements th
8300: 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c  at were original
8310: 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62  ly in the.** tab
8320: 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63  le. To get an ac
8330: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
8340: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
8350: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
8360: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
8370: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
8380: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  nstead..**.** If
8390: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
83a0: 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
83b0: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
83c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
83d0: 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
83e0: 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ine is running t
83f0: 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
8400: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75  alue of this rou
8410: 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  tine.** is undef
8420: 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
8430: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
8440: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
8450: 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
8460: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
8470: 64 69 66 69 65 64 0a 2a 2a 2a 0a 2a 2a 20 54 68  dified.***.** Th
8480: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
8490: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
84a0: 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
84b0: 74 68 61 74 20 68 61 76 65 20 62 65 65 6e 0a 2a  that have been.*
84c0: 2a 20 6d 6f 64 69 66 69 65 64 20 62 79 20 49 4e  * modified by IN
84d0: 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
84e0: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
84f0: 73 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  s since the data
8500: 62 61 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77  base handle.** w
8510: 61 73 20 6f 70 65 6e 65 64 2e 20 54 68 69 73 20  as opened. This 
8520: 69 6e 63 6c 75 64 65 73 20 55 50 44 41 54 45 2c  includes UPDATE,
8530: 20 49 4e 53 45 52 54 20 61 6e 64 20 44 45 4c 45   INSERT and DELE
8540: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 65 78  TE statements ex
8550: 65 63 75 74 65 64 0a 2a 2a 20 61 73 20 70 61 72  ecuted.** as par
8560: 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
8570: 67 72 61 6d 73 2e 20 41 6c 6c 20 63 68 61 6e 67  grams. All chang
8580: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  es are counted a
8590: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 0a 2a 2a  s soon as the.**
85a0: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
85b0: 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
85c0: 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
85d0: 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
85e0: 6c 65 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  le is.** passed 
85f0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
8600: 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
8610: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
8620: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
8630: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
8640: 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  e()] interface..
8650: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
8660: 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d  lements the comm
8670: 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  and "DELETE FROM
8680: 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20   table" without 
8690: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a  a WHERE clause.*
86a0: 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e  * by dropping an
86b0: 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65  d recreating the
86c0: 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69   table.  (This i
86d0: 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68  s much faster th
86e0: 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f  an going.** thro
86f0: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
8700: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
8710: 65 6e 74 73 20 66 6f 72 6d 20 74 68 65 20 74 61  ents form the ta
8720: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
8730: 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69  f.** this optimi
8740: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e  zation, the chan
8750: 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45  ge count for "DE
8760: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
8770: 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f   will be.** zero
8780: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
8790: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
87a0: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
87b0: 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68  originally in th
87c0: 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67  e.** table. To g
87d0: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
87e0: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
87f0: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
8800: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
8810: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
8820: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a  ERE 1" instead..
8830: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
8840: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
8850: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
8860: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
8870: 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74  ction.** while t
8880: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
8890: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
88a0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
88b0: 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
88c0: 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
88d0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
88e0: 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
88f0: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
8900: 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
8910: 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
8920: 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73  Query.**.** This
8930: 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
8940: 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
8950: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
8960: 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
8970: 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
8980: 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
8990: 74 79 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  ty.  This routin
89a0: 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
89b0: 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
89c0: 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
89d0: 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
89e0: 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
89f0: 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
8a00: 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
8a10: 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
8a20: 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
8a30: 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
8a40: 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66  .**.** It is saf
8a50: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
8a60: 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
8a70: 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
8a80: 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
8a90: 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
8aa0: 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
8ab0: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
8ac0: 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
8ad0: 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
8ae0: 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
8af0: 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
8b00: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 0a  connection that.
8b10: 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
8b20: 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
8b30: 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
8b40: 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
8b50: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 20 6f 70  **.** The SQL op
8b60: 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
8b70: 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
8b80: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
8b90: 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49  INTERRUPT]..** I
8ba0: 66 20 61 6e 20 69 6e 74 65 72 72 75 70 74 65 64  f an interrupted
8bb0: 20 6f 70 65 72 61 74 69 6f 6e 20 77 61 73 20 61   operation was a
8bc0: 6e 20 75 70 64 61 74 65 20 74 68 61 74 20 69 73  n update that is
8bd0: 20 69 6e 73 69 64 65 20 61 6e 0a 2a 2a 20 65 78   inside an.** ex
8be0: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
8bf0: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
8c00: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ire transaction 
8c10: 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 0a 2a  will be rolled.*
8c20: 2a 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  * back automatic
8c30: 61 6c 6c 79 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ally..*/.void sq
8c40: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
8c50: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
8c60: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
8c70: 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
8c80: 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
8c90: 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
8ca0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
8cb0: 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 67  rn true if the g
8cc0: 69 76 65 6e 20 69 6e 70 75 74 20 73 74 72 69 6e  iven input strin
8cd0: 67 20 63 6f 6d 70 72 69 73 65 73 0a 2a 2a 20 6f  g comprises.** o
8ce0: 6e 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c  ne or more compl
8cf0: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
8d00: 74 73 2e 20 46 6f 72 20 74 68 65 20 73 71 6c 69  ts. For the sqli
8d10: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 63  te3_complete() c
8d20: 61 6c 6c 2c 0a 2a 2a 20 74 68 65 20 70 61 72 61  all,.** the para
8d30: 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
8d40: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  nul-terminated U
8d50: 54 46 2d 38 20 73 74 72 69 6e 67 2e 20 46 6f 72  TF-8 string. For
8d60: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
8d70: 6c 65 74 65 31 36 28 29 2c 20 61 20 6e 75 6c 2d  lete16(), a nul-
8d80: 74 65 72 6d 69 6e 61 74 65 64 20 6d 61 63 68 69  terminated machi
8d90: 6e 65 20 62 79 74 65 20 6f 72 64 65 72 20 55 54  ne byte order UT
8da0: 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
8db0: 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
8dc0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
8dd0: 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
8de0: 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
8df0: 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
8e00: 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
8e10: 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
8e20: 20 66 6f 72 6d 73 20 6f 6e 65 20 6f 72 20 6d 6f   forms one or mo
8e30: 72 65 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20  re complete SQL 
8e40: 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 0a 2a 2a  statements or.**
8e50: 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
8e60: 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
8e70: 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
8e80: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 74  e statements int
8e90: 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
8ea0: 70 61 72 73 69 6e 67 2e 20 54 68 65 20 61 6c 67  parsing. The alg
8eb0: 6f 72 69 74 68 6d 20 69 73 20 73 69 6d 70 6c 65  orithm is simple
8ec0: 2e 20 20 49 66 20 74 68 65 20 0a 2a 2a 20 6c 61  .  If the .** la
8ed0: 73 74 20 74 6f 6b 65 6e 20 6f 74 68 65 72 20 74  st token other t
8ee0: 68 61 6e 20 73 70 61 63 65 73 20 61 6e 64 20 63  han spaces and c
8ef0: 6f 6d 6d 65 6e 74 73 20 69 73 20 61 20 73 65 6d  omments is a sem
8f00: 69 63 6f 6c 6f 6e 2c 20 74 68 65 6e 20 72 65 74  icolon, then ret
8f10: 75 72 6e 20 0a 2a 2a 20 74 72 75 65 2e 20 20 41  urn .** true.  A
8f20: 63 74 75 61 6c 6c 79 2c 20 74 68 65 20 61 6c 67  ctually, the alg
8f30: 6f 72 69 74 68 6d 20 69 73 20 61 20 6c 69 74 74  orithm is a litt
8f40: 6c 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  le more complica
8f50: 74 65 64 20 74 68 61 6e 20 74 68 61 74 0a 2a 2a  ted than that.**
8f60: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 61   in order to dea
8f70: 6c 20 77 69 74 68 20 74 72 69 67 67 65 72 73 2c  l with triggers,
8f80: 20 62 75 74 20 74 68 65 20 62 61 73 69 63 20 69   but the basic i
8f90: 64 65 61 20 69 73 20 74 68 65 20 73 61 6d 65 3a  dea is the same:
8fa0: 20 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65    the.** stateme
8fb0: 6e 74 20 69 73 20 6e 6f 74 20 63 6f 6d 70 6c 65  nt is not comple
8fc0: 74 65 20 75 6e 6c 65 73 73 20 69 74 20 65 6e 64  te unless it end
8fd0: 73 20 69 6e 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  s in a semicolon
8fe0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
8ff0: 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
9000: 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
9010: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
9020: 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
9030: 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
9040: 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
9050: 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
9060: 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
9070: 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69  Errors.**.** Thi
9080: 73 20 72 6f 75 74 69 6e 65 20 69 64 65 6e 74 69  s routine identi
9090: 66 69 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  fies a callback 
90a0: 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
90b0: 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ght be invoked.*
90c0: 2a 20 77 68 65 6e 65 76 65 72 20 61 6e 20 61 74  * whenever an at
90d0: 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
90e0: 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
90f0: 20 74 61 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20   table .** that 
9100: 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6f  another thread o
9110: 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
9120: 63 6b 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cked..** If the 
9130: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
9140: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
9150: 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 28 6f 72  ITE_BUSY].** (or
9160: 20 73 6f 6d 65 74 69 6d 65 73 20 5b 53 51 4c 49   sometimes [SQLI
9170: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
9180: 5d 29 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ]).** is returne
9190: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
91a0: 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
91b0: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20  the lock..** If 
91c0: 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
91d0: 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  k is not NULL, t
91e0: 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62  hen the.** callb
91f0: 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  ack will be invo
9200: 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
9210: 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20  uments.  The.** 
9220: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
9230: 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73  o the handler is
9240: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
9250: 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
9260: 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
9270: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
9280: 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  his routine.  Th
9290: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
92a0: 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64  t to.** the hand
92b0: 6c 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ler is the numbe
92c0: 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
92d0: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
92e0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
92f0: 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
9300: 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 49 66 20  cking event. If 
9310: 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
9320: 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
9330: 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
9340: 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
9350: 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
9360: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
9370: 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
9380: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
9390: 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
93a0: 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68  turned..** If th
93b0: 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
93c0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
93d0: 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
93e0: 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
93f0: 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
9400: 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
9410: 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
9420: 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
9430: 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
9440: 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
9450: 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
9460: 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62 65 20  t.** it will be 
9470: 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
9480: 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
9490: 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c  ntion..** If SQL
94a0: 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
94b0: 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
94c0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6f   busy handler co
94d0: 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a  uld result in.**
94e0: 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
94f0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
9500: 49 54 45 5f 42 55 53 59 5d 20 69 6e 73 74 65 61  ITE_BUSY] instea
9510: 64 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  d..** Consider a
9520: 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
9530: 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
9540: 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
9550: 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
9560: 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
9570: 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
9580: 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
9590: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
95a0: 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
95b0: 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
95c0: 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
95d0: 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
95e0: 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
95f0: 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
9600: 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
9610: 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
9620: 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
9630: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
9640: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
9650: 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
9660: 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
9670: 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
9680: 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
9690: 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
96a0: 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
96b0: 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
96c0: 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
96d0: 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
96e0: 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
96f0: 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
9700: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
9710: 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
9720: 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
9730: 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
9740: 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
9750: 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
9760: 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
9770: 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
9780: 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
9790: 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
97a0: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
97b0: 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
97c0: 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
97d0: 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
97e0: 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
97f0: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 77 68 65  ERR_BLOCKED] whe
9800: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 69  n.** SQLite is i
9810: 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
9820: 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
9830: 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
9840: 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
9850: 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
9860: 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
9870: 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
9880: 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
9890: 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
98a0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
98b0: 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
98c0: 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
98d0: 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
98e0: 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
98f0: 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
9900: 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
9910: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
9920: 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
9930: 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
9940: 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69  * readers.  If i
9950: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
9960: 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
9970: 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
9980: 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
9990: 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
99a0: 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
99b0: 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
99c0: 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
99d0: 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
99e0: 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
99f0: 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
9a00: 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
9a10: 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
9a20: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
9a30: 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
9a40: 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
9a50: 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
9a60: 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
9a70: 20 63 68 61 6e 67 65 73 2e 20 53 65 65 20 74 68   changes. See th
9a80: 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74  e.** <a href="ht
9a90: 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e  tp://www.sqlite.
9aa0: 6f 72 67 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  org/cvstrac/wiki
9ab0: 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
9ac0: 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
9ad0: 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
9ae0: 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
9af0: 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
9b00: 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
9b10: 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
9b20: 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
9b30: 09 0a 2a 2a 20 53 71 6c 69 74 65 20 69 73 20 72  ..** Sqlite is r
9b40: 65 2d 65 6e 74 72 61 6e 74 2c 20 73 6f 20 74 68  e-entrant, so th
9b50: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  e busy handler m
9b60: 61 79 20 73 74 61 72 74 20 61 20 6e 65 77 20 71  ay start a new q
9b70: 75 65 72 79 2e 20 0a 2a 2a 20 28 49 74 20 69 73  uery. .** (It is
9b80: 20 6e 6f 74 20 63 6c 65 61 72 20 77 68 79 20 61   not clear why a
9b90: 6e 79 6f 6e 65 20 77 6f 75 6c 64 20 65 76 65 72  nyone would ever
9ba0: 79 20 77 61 6e 74 20 74 6f 20 64 6f 20 74 68 69  y want to do thi
9bb0: 73 2c 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  s, but it.** is 
9bc0: 61 6c 6c 6f 77 65 64 2c 20 69 6e 20 74 68 65 6f  allowed, in theo
9bd0: 72 79 2e 29 20 20 42 75 74 20 74 68 65 20 62 75  ry.)  But the bu
9be0: 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 6e  sy handler may n
9bf0: 6f 74 20 63 6c 6f 73 65 20 74 68 65 0a 2a 2a 20  ot close the.** 
9c00: 64 61 74 61 62 61 73 65 2e 20 20 43 6c 6f 73 69  database.  Closi
9c10: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
9c20: 66 72 6f 6d 20 61 20 62 75 73 79 20 68 61 6e 64  from a busy hand
9c30: 6c 65 72 20 77 69 6c 6c 20 64 65 6c 65 74 65 20  ler will delete 
9c40: 0a 2a 2a 20 64 61 74 61 20 73 74 72 75 63 74 75  .** data structu
9c50: 72 65 73 20 6f 75 74 20 66 72 6f 6d 20 75 6e 64  res out from und
9c60: 65 72 20 74 68 65 20 65 78 65 63 75 74 69 6e 67  er the executing
9c70: 20 71 75 65 72 79 20 61 6e 64 20 77 69 6c 6c 20   query and will 
9c80: 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 73  .** probably res
9c90: 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
9ca0: 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
9cb0: 74 68 65 72 20 72 75 6e 74 69 6d 65 20 65 72 72  ther runtime err
9cc0: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  or..**.** There 
9cd0: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
9ce0: 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
9cf0: 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
9d00: 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ch database.** c
9d10: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 74  onnection.  Sett
9d20: 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
9d30: 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
9d40: 79 20 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e 0a  y previous one..
9d50: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c  ** Note that cal
9d60: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
9d70: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 69  sy_timeout()] wi
9d80: 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
9d90: 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 79  lear.** the busy
9da0: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
9db0: 57 68 65 6e 20 6f 70 65 72 61 74 69 6e 67 20 69  When operating i
9dc0: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  n [sqlite3_enabl
9dd0: 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c  e_shared_cache |
9de0: 20 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f   shared cache mo
9df0: 64 65 5d 2c 0a 2a 2a 20 6f 6e 6c 79 20 61 20 73  de],.** only a s
9e00: 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
9e10: 65 72 20 63 61 6e 20 62 65 20 64 65 66 69 6e 65  er can be define
9e20: 64 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62  d for each datab
9e30: 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 53 6f 20  ase file..** So 
9e40: 69 66 20 74 77 6f 20 64 61 74 61 62 61 73 65 20  if two database 
9e50: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 73 68 61 72  connections shar
9e60: 65 20 61 20 73 69 6e 67 6c 65 20 63 61 63 68 65  e a single cache
9e70: 2c 20 74 68 65 6e 20 63 68 61 6e 67 69 6e 67 0a  , then changing.
9e80: 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
9e90: 6c 65 72 20 6f 6e 20 6f 6e 65 20 63 6f 6e 6e 65  ler on one conne
9ea0: 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 73 6f 20  ction will also 
9eb0: 63 68 61 6e 67 65 20 74 68 65 20 62 75 73 79 0a  change the busy.
9ec0: 2a 2a 20 68 61 6e 64 6c 65 72 20 69 6e 20 74 68  ** handler in th
9ed0: 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69  e other connecti
9ee0: 6f 6e 2e 20 20 54 68 65 20 62 75 73 79 20 68 61  on.  The busy ha
9ef0: 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  ndler is invoked
9f00: 0a 2a 2a 20 69 6e 20 74 68 65 20 74 68 72 65 61  .** in the threa
9f10: 64 20 74 68 61 74 20 77 61 73 20 72 75 6e 6e 69  d that was runni
9f20: 6e 67 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49  ng when the SQLI
9f30: 54 45 5f 42 55 53 59 20 77 61 73 20 68 69 74 2e  TE_BUSY was hit.
9f40: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
9f50: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
9f60: 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
9f70: 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
9f80: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
9f90: 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
9fa0: 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 54 68 69 73  meout.**.** This
9fb0: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
9fc0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 74 68 61  busy handler tha
9fd0: 74 20 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77  t sleeps for a w
9fe0: 68 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74  hile when a.** t
9ff0: 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
a000: 20 54 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c   The handler wil
a010: 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
a020: 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a   times until .**
a030: 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
a040: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
a050: 6c 65 65 70 69 6e 67 20 68 61 76 65 20 62 65 65  leeping have bee
a060: 6e 20 64 6f 6e 65 2e 20 20 41 66 74 65 72 0a 2a  n done.  After.*
a070: 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  * "ms" milliseco
a080: 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
a090: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
a0a0: 75 72 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a 20  urns 0 which.** 
a0b0: 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
a0c0: 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
a0d0: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
a0e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
a0f0: 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
a100: 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
a110: 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
a120: 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
a130: 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
a140: 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
a150: 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
a160: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
a170: 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
a180: 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
a190: 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
a1a0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
a1b0: 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f  nection.  If ano
a1c0: 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
a1d0: 72 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 0a  r was defined  .
a1e0: 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  ** (using [sqlit
a1f0: 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
a200: 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
a210: 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
a220: 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
a230: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
a240: 20 63 6c 65 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74   cleared..*/.int
a250: 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
a260: 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
a270: 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
a280: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
a290: 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
a2a0: 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
a2b0: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6e 65  es.**.** This ne
a2c0: 78 74 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  xt routine is a 
a2d0: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70  convenience wrap
a2e0: 70 65 72 20 61 72 6f 75 6e 64 20 5b 73 71 6c 69  per around [sqli
a2f0: 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2a 20  te3_exec()]..** 
a300: 49 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  Instead of invok
a310: 69 6e 67 20 61 20 75 73 65 72 2d 73 75 70 70 6c  ing a user-suppl
a320: 69 65 64 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  ied callback for
a330: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65   each row of the
a340: 0a 2a 2a 20 72 65 73 75 6c 74 2c 20 74 68 69 73  .** result, this
a350: 20 72 6f 75 74 69 6e 65 20 72 65 6d 65 6d 62 65   routine remembe
a360: 72 73 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74  rs each row of t
a370: 68 65 20 72 65 73 75 6c 74 20 69 6e 20 6d 65 6d  he result in mem
a380: 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ory.** obtained 
a390: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
a3a0: 6c 6c 6f 63 28 29 5d 2c 20 74 68 65 6e 20 72 65  lloc()], then re
a3b0: 74 75 72 6e 73 20 61 6c 6c 20 6f 66 20 74 68 65  turns all of the
a3c0: 20 72 65 73 75 6c 74 20 61 66 74 65 72 20 74 68   result after th
a3d0: 65 0a 2a 2a 20 71 75 65 72 79 20 68 61 73 20 66  e.** query has f
a3e0: 69 6e 69 73 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20  inished. .**.** 
a3f0: 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 73  As an example, s
a400: 75 70 70 6f 73 65 20 74 68 65 20 71 75 65 72 79  uppose the query
a410: 20 72 65 73 75 6c 74 20 77 68 65 72 65 20 74 68   result where th
a420: 69 73 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20  is table:.**.** 
a430: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
a440: 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
a450: 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
a460: 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
a470: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
a480: 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
a490: 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
a4a0: 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
a4b0: 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
a4c0: 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
a4d0: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
a4e0: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66  kquote>.**.** If
a4f0: 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e   the 3rd argumen
a500: 74 20 77 65 72 65 20 26 61 7a 52 65 73 75 6c 74  t were &azResult
a510: 20 74 68 65 6e 20 61 66 74 65 72 20 74 68 65 20   then after the 
a520: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
a530: 0a 2a 2a 20 61 7a 52 65 73 75 6c 74 20 77 69 6c  .** azResult wil
a540: 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 66 6f  l contain the fo
a550: 6c 6c 6f 77 69 6e 67 20 64 61 74 61 3a 0a 2a 2a  llowing data:.**
a560: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
a570: 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
a580: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
a590: 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
a5a0: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
a5b0: 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
a5c0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
a5d0: 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
a5e0: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
a5f0: 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
a600: 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
a610: 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
a620: 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
a630: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
a640: 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
a650: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
a660: 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
a670: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
a680: 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
a690: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
a6a0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  quote>.**.** Not
a6b0: 69 63 65 20 74 68 61 74 20 74 68 65 72 65 20 69  ice that there i
a6c0: 73 20 61 6e 20 65 78 74 72 61 20 72 6f 77 20 6f  s an extra row o
a6d0: 66 20 64 61 74 61 20 63 6f 6e 74 61 69 6e 69 6e  f data containin
a6e0: 67 20 74 68 65 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  g the column.** 
a6f0: 68 65 61 64 65 72 73 2e 20 20 42 75 74 20 74 68  headers.  But th
a700: 65 20 2a 6e 72 6f 77 20 72 65 74 75 72 6e 20 76  e *nrow return v
a710: 61 6c 75 65 20 69 73 20 73 74 69 6c 6c 20 33 2e  alue is still 3.
a720: 20 20 2a 6e 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a    *ncolumn is.**
a730: 20 73 65 74 20 74 6f 20 32 2e 20 20 49 6e 20 67   set to 2.  In g
a740: 65 6e 65 72 61 6c 2c 20 74 68 65 20 6e 75 6d 62  eneral, the numb
a750: 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 73  er of values ins
a760: 65 72 74 65 64 20 69 6e 74 6f 20 61 7a 52 65 73  erted into azRes
a770: 75 6c 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 28  ult.** will be (
a780: 28 2a 6e 72 6f 77 29 20 2b 20 31 29 2a 28 2a 6e  (*nrow) + 1)*(*n
a790: 63 6f 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a 2a 20 41  column)..**.** A
a7a0: 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67  fter the calling
a7b0: 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69   function has fi
a7c0: 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
a7d0: 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75   result, it shou
a7e0: 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20  ld .** pass the 
a7f0: 72 65 73 75 6c 74 20 64 61 74 61 20 70 6f 69 6e  result data poin
a800: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
a810: 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
a820: 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65  rder to .** rele
a830: 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
a840: 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65  hat was malloc-e
a850: 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
a860: 68 65 20 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b  he way the .** [
a870: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
a880: 5d 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 63  ] happens, the c
a890: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
a8a0: 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
a8b0: 63 61 6c 6c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  call .** [sqlite
a8c0: 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
a8d0: 6c 79 2e 20 20 4f 6e 6c 79 20 5b 73 71 6c 69 74  ly.  Only [sqlit
a8e0: 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
a8f0: 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
a900: 61 73 65 20 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  ase .** the memo
a910: 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
a920: 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
a930: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
a940: 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
a950: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 66 72  s the same as fr
a960: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  om [sqlite3_exec
a970: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
a980: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
a990: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
a9a0: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
a9b0: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
a9c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
a9d0: 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ,       /* SQL t
a9e0: 6f 20 62 65 20 65 78 65 63 75 74 65 64 20 2a 2f  o be executed */
a9f0: 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c  .  char ***resul
aa00: 74 70 2c 20 20 20 20 20 20 20 2f 2a 20 52 65 73  tp,       /* Res
aa10: 75 6c 74 20 77 72 69 74 74 65 6e 20 74 6f 20 61  ult written to a
aa20: 20 63 68 61 72 20 2a 5b 5d 20 20 74 68 61 74 20   char *[]  that 
aa30: 74 68 69 73 20 70 6f 69 6e 74 73 20 74 6f 20 2a  this points to *
aa40: 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20  /.  int *nrow,  
aa50: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
aa60: 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
aa70: 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
aa80: 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75   */.  int *ncolu
aa90: 6d 6e 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  mn,          /* 
aaa0: 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
aab0: 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
aac0: 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
aad0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
aae0: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
aaf0: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
ab00: 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
ab10: 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
ab20: 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
ab30: 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
ab40: 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
ab50: 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
ab60: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
ab70: 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b  nes are workalik
ab80: 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
ab90: 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
aba0: 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
abb0: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
abc0: 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54  library..**.** T
abd0: 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
abe0: 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
abf0: 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
ac00: 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
ac10: 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
ac20: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
ac30: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
ac40: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
ac50: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
ac60: 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
ac70: 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
ac80: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
ac90: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
aca0: 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65  ].  Both routine
acb0: 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
acc0: 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
acd0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
ace0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
acf0: 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
ad00: 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
ad10: 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
ad20: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73  ring..**.** In s
ad30: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
ad40: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
ad50: 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
ad60: 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
ad70: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
ad80: 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
ad90: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
ada0: 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
adb0: 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
adc0: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
add0: 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
ade0: 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
adf0: 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20  rst parameter.  
ae00: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
ae10: 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
ae20: 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
ae30: 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
ae40: 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20  rom snprintf(). 
ae50: 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
ae60: 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
ae70: 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
ae80: 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
ae90: 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
aea0: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
aeb0: 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20  ity.  Note also 
aec0: 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
aed0: 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
aee0: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
aef0: 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
af00: 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
af10: 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
af20: 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
af30: 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
af40: 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68  er.  We admit th
af50: 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
af60: 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
af70: 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
af80: 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
af90: 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
afa0: 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
afb0: 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
afc0: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
afd0: 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
afe0: 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
aff0: 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
b000: 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67  y..**.** As long
b010: 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
b020: 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
b030: 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
b040: 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
b050: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
b060: 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
b070: 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
b080: 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 74  ated.  The first
b090: 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
b0a0: 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
b0b0: 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
b0c0: 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
b0d0: 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
b0e0: 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
b0f0: 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
b100: 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
b110: 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
b120: 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
b130: 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
b140: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
b150: 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
b160: 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
b170: 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
b180: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
b190: 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
b1a0: 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
b1b0: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
b1c0: 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
b1d0: 69 6e 74 66 20 66 6f 72 6d 61 74 74 69 6e 67 20  intf formatting 
b1e0: 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
b1f0: 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
b200: 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
b210: 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
b220: 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
b230: 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77   The %q option w
b240: 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
b250: 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
b260: 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
b270: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
b280: 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
b290: 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
b2a0: 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
b2b0: 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
b2c0: 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
b2d0: 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
b2e0: 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
b2f0: 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69  eral.  By doubli
b300: 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
b310: 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
b320: 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
b330: 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
b340: 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
b350: 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
b360: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
b370: 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20  xample, so some 
b380: 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
b390: 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
b3a0: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
b3b0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
b3c0: 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
b3d0: 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
b3e0: 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
b3f0: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
b400: 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
b410: 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
b420: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
b430: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
b440: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
b450: 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
b460: 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
b470: 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
b480: 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
b490: 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
b4a0: 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
b4b0: 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
b4c0: 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
b4d0: 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
b4e0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
b4f0: 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
b500: 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
b510: 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
b520: 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
b530: 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
b540: 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
b550: 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
b560: 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
b570: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
b580: 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
b590: 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
b5a0: 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
b5b0: 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
b5c0: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
b5d0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
b5e0: 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
b5f0: 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
b600: 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
b610: 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
b620: 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
b630: 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
b640: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
b650: 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
b660: 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
b670: 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
b680: 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
b690: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
b6a0: 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
b6b0: 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
b6c0: 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
b6d0: 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
b6e0: 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61   you.** should a
b6f0: 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
b700: 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
b710: 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
b720: 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a  nto a string .**
b730: 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
b740: 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
b750: 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
b760: 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
b770: 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
b780: 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
b790: 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
b7a0: 20 73 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20   string.  Or if 
b7b0: 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
b7c0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
b7d0: 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
b7e0: 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
b7f0: 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
b800: 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
b810: 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65   single.** quote
b820: 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  s) in place of t
b830: 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53  he %Q option.  S
b840: 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
b850: 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
b860: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
b870: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
b880: 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
b890: 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
b8a0: 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
b8b0: 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
b8c0: 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
b8d0: 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
b8e0: 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
b8f0: 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
b900: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
b910: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
b920: 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
b930: 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
b940: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
b950: 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
b960: 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
b970: 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
b980: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
b990: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a  r..**.** The "%z
b9a0: 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
b9b0: 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c  ion works exactl
b9c0: 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68  y like "%s" with
b9d0: 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
b9e0: 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
b9f0: 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
ba00: 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
ba10: 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
ba20: 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
ba30: 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
ba40: 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
ba50: 6e 67 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  ng..*/.char *sql
ba60: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
ba70: 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
ba80: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
ba90: 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
baa0: 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
bab0: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
bac0: 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
bad0: 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
bae0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
baf0: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
bb00: 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
bb10: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
bb20: 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
bb30: 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
bb40: 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
bb50: 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
bb60: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
bb70: 65 65 64 73 2e 20 28 53 65 65 20 74 68 65 20 65  eeds. (See the e
bb80: 78 63 65 70 74 69 6f 6e 20 62 65 6c 6f 77 2e 29  xception below.)
bb90: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
bba0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
bbb0: 2a 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20  * of the memory 
bbc0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
bbd0: 73 74 65 6d 20 75 73 65 73 20 74 68 65 20 6d 61  stem uses the ma
bbe0: 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
bbf0: 29 0a 2a 2a 20 61 6e 64 20 66 72 65 65 28 29 20  ).** and free() 
bc00: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
bc10: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
bc20: 72 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66  ry.  However, if
bc30: 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 63   .** SQLite is c
bc40: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
bc50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72 65   following C pre
bc60: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a  processor macro.
bc70: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
bc80: 65 3e 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  e> SQLITE_OMIT_M
bc90: 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
bca0: 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a   </blockquote>.*
bcb0: 2a 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 69 6d 70  *.** then no imp
bcc0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 70  lementation is p
bcd0: 72 6f 76 69 64 65 64 20 66 6f 72 20 74 68 65 73  rovided for thes
bce0: 65 20 72 6f 75 74 69 6e 65 73 20 62 79 0a 2a 2a  e routines by.**
bcf0: 20 53 51 4c 69 74 65 2e 20 20 54 68 65 20 61 70   SQLite.  The ap
bd00: 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 6c  plication that l
bd10: 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c  inks against SQL
bd20: 69 74 65 20 69 73 0a 2a 2a 20 65 78 70 65 63 74  ite is.** expect
bd30: 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20 69 74  ed to provide it
bd40: 73 20 6f 77 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  s own implementa
bd50: 74 69 6f 6e 2e 20 20 49 66 20 74 68 65 20 61 70  tion.  If the ap
bd60: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65  plication.** doe
bd70: 73 20 70 72 6f 76 69 64 65 20 69 74 73 20 6f 77  s provide its ow
bd80: 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
bd90: 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
bda0: 6e 65 73 2c 20 74 68 65 6e 0a 2a 2a 20 69 74 20  nes, then.** it 
bdb0: 6d 75 73 74 20 61 6c 73 6f 20 70 72 6f 76 69 64  must also provid
bdc0: 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e an implementat
bdd0: 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 5b 73 71 6c  ions for.** [sql
bde0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
bdf0: 6d 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6d  m()], [sqlite3_m
be00: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 2c 20 61  emory_used()], a
be10: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
be20: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
be30: 29 5d 2e 20 20 54 68 65 20 61 6c 74 65 72 6e 61  )].  The alterna
be40: 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tive implementat
be50: 69 6f 6e 73 0a 2a 2a 20 66 6f 72 20 74 68 65 73  ions.** for thes
be60: 65 20 6c 61 73 74 20 74 68 72 65 65 20 72 6f 75  e last three rou
be70: 74 69 6e 65 73 20 6e 65 65 64 20 6e 6f 74 20 61  tines need not a
be80: 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2c 20 62 75  ctually work, bu
be90: 74 0a 2a 2a 20 73 74 75 62 20 66 75 6e 63 74 69  t.** stub functi
bea0: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 61 72 65  ons at least are
beb0: 20 6e 65 65 64 65 64 20 74 6f 20 73 74 61 74 69   needed to stati
bec0: 73 66 79 20 74 68 65 20 6c 69 6e 6b 65 72 2e 0a  sfy the linker..
bed0: 2a 2a 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20  ** SQLite never 
bee0: 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 6d  calls [sqlite3_m
bef0: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
bf00: 29 5d 20 69 74 73 65 6c 66 2c 20 62 75 74 0a 2a  )] itself, but.*
bf10: 2a 20 74 68 65 20 73 79 6d 62 6f 6c 20 69 73 20  * the symbol is 
bf20: 69 6e 63 6c 75 64 65 64 20 69 6e 20 61 20 74 61  included in a ta
bf30: 62 6c 65 20 61 73 20 70 61 72 74 20 6f 66 20 74  ble as part of t
bf40: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  he.** [sqlite3_l
bf50: 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
bf60: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
bf70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
bf80: 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 20 61 6e 64  ory_alarm()] and
bf90: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
bfa0: 5f 75 73 65 64 28 29 5d 20 69 6e 74 65 72 66 61  _used()] interfa
bfb0: 63 65 73 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ces.** are calle
bfc0: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 6f  d by [sqlite3_so
bfd0: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d  ft_heap_limit()]
bfe0: 20 61 6e 64 20 77 6f 72 6b 69 6e 67 20 69 6d 70   and working imp
bff0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
c000: 6f 66 20 62 6f 74 68 20 72 6f 75 74 69 6e 65 73  of both routines
c010: 20 6d 75 73 74 20 62 65 20 70 72 6f 76 69 64 65   must be provide
c020: 64 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 6f  d if [sqlite3_so
c030: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d  ft_heap_limit()]
c040: 0a 2a 2a 20 69 73 20 74 6f 20 6f 70 65 72 61 74  .** is to operat
c050: 65 20 63 6f 72 72 65 63 74 6c 79 2e 0a 2a 2a 0a  e correctly..**.
c060: 2a 2a 20 3c 62 3e 45 78 63 65 70 74 69 6f 6e 3a  ** <b>Exception:
c070: 3c 2f 62 3e 20 54 68 65 20 77 69 6e 64 6f 77 73  </b> The windows
c080: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
c090: 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
c0a0: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
c0b0: 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
c0c0: 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
c0d0: 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
c0e0: 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
c0f0: 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
c100: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
c110: 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
c120: 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
c130: 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
c140: 74 69 63 75 6c 61 72 20 77 69 6e 64 6f 77 73 0a  ticular windows.
c150: 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
c160: 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
c170: 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
c180: 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
c190: 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
c1a0: 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
c1b0: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
c1c0: 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
c1d0: 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
c1e0: 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a  LITE_NOMEM]..*/.
c1f0: 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
c200: 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
c210: 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
c220: 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
c230: 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
c240: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
c250: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
c260: 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
c270: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64  tics.**.** In ad
c280: 64 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 62 61  dition to the ba
c290: 73 69 63 20 74 68 72 65 65 20 61 6c 6c 6f 63 61  sic three alloca
c2a0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a 2a  tion routines .*
c2b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
c2c0: 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
c2d0: 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
c2e0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c  ite3_realloc()],
c2f0: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
c300: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
c310: 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74  tem included wit
c320: 68 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  h the SQLite.** 
c330: 73 6f 75 72 63 65 73 20 70 72 6f 76 69 64 65 73  sources provides
c340: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
c350: 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 0a  shown below..**.
c360: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 6f 66 20  ** The first of 
c370: 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
c380: 65 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  es returns the a
c390: 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20  mount of memory 
c3a0: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  .** currently ou
c3b0: 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
c3c0: 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
c3d0: 64 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a  d).  The second.
c3e0: 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c  ** returns the l
c3f0: 61 72 67 65 73 74 20 69 6e 73 74 61 6e 74 61 6e  argest instantan
c400: 65 6f 75 73 20 61 6d 6f 75 6e 74 20 6f 66 20 6f  eous amount of o
c410: 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 6d 65  utstanding.** me
c420: 6d 6f 72 79 2e 20 20 54 68 65 20 68 69 67 68 77  mory.  The highw
c430: 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
c440: 65 74 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  et if the argume
c450: 6e 74 20 69 73 0a 2a 2a 20 74 72 75 65 2e 0a 2a  nt is.** true..*
c460: 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65  *.** The impleme
c470: 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
c480: 20 72 6f 75 74 69 6e 65 73 20 69 6e 20 74 68 65   routines in the
c490: 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20   SQLite core.** 
c4a0: 69 73 20 6f 6d 69 74 74 65 64 20 69 66 20 74 68  is omitted if th
c4b0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
c4c0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
c4d0: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4d 49  he.** SQLITE_OMI
c4e0: 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
c4f0: 49 4f 4e 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  ION macro define
c500: 64 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  d.  In that case
c510: 2c 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  ,.** the applica
c520: 74 69 6f 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20  tion that links 
c530: 53 51 4c 69 74 65 20 6d 75 73 74 20 70 72 6f 76  SQLite must prov
c540: 69 64 65 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 61  ide its own.** a
c550: 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65  lternative imple
c560: 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 65 65 20  mentation.  See 
c570: 74 68 65 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  the documentatio
c580: 6e 20 6f 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  n on.** [sqlite3
c590: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 61  _malloc()] for a
c5a0: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
c5b0: 61 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ation..*/.sqlite
c5c0: 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
c5d0: 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
c5e0: 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
c5f0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
c600: 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
c610: 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
c620: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
c630: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 41 6c 61  y Allocation Ala
c640: 72 6d 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  rms.**.** The [s
c650: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
c660: 61 72 6d 5d 20 72 6f 75 74 69 6e 65 20 69 73 20  arm] routine is 
c670: 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
c680: 0a 2a 2a 20 61 20 63 61 6c 6c 62 61 63 6b 20 6f  .** a callback o
c690: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
c6a0: 69 6f 6e 20 65 76 65 6e 74 73 2e 0a 2a 2a 0a 2a  ion events..**.*
c6b0: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
c6c0: 65 67 69 73 74 65 72 73 20 6f 72 20 63 6c 65 61  egisters or clea
c6d0: 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 73 20 74  rs a callbacks t
c6e0: 68 61 74 20 66 69 72 65 73 20 77 68 65 6e 0a 2a  hat fires when.*
c6f0: 2a 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * the amount of 
c700: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
c710: 20 65 78 63 65 65 64 73 20 69 54 68 72 65 73 68   exceeds iThresh
c720: 6f 6c 64 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 61 20  old.  Only.** a 
c730: 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
c740: 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
c750: 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  d at a time.  Ea
c760: 63 68 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ch call.** to [s
c770: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
c780: 61 72 6d 28 29 5d 20 6f 76 65 72 77 72 69 74 65  arm()] overwrite
c790: 73 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  s the previous c
c7a0: 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
c7b0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 64 69 73 61  callback is disa
c7c0: 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
c7d0: 78 43 61 6c 6c 62 61 63 6b 20 74 6f 20 61 20 4e  xCallback to a N
c7e0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 0a  ULL.** pointer..
c7f0: 2a 2a 20 0a 2a 2a 20 54 68 65 20 70 61 72 61 6d  ** .** The param
c800: 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
c810: 6c 62 61 63 6b 20 61 72 65 20 74 68 65 20 70 41  lback are the pA
c820: 72 67 20 76 61 6c 75 65 2c 20 74 68 65 20 0a 2a  rg value, the .*
c830: 2a 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  * amount of memo
c840: 72 79 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20  ry currently in 
c850: 75 73 65 2c 20 61 6e 64 20 74 68 65 20 73 69 7a  use, and the siz
c860: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f  e of the.** allo
c870: 63 61 74 69 6f 6e 20 74 68 61 74 20 70 72 6f 76  cation that prov
c880: 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  oked the callbac
c890: 6b 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  k.  The callback
c8a0: 20 77 69 6c 6c 0a 2a 2a 20 70 72 65 73 75 6d 61   will.** presuma
c8b0: 62 6c 79 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  bly invoke [sqli
c8c0: 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66  te3_free()] to f
c8d0: 72 65 65 20 75 70 20 6d 65 6d 6f 72 79 20 73 70  ree up memory sp
c8e0: 61 63 65 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ace..** The call
c8f0: 62 61 63 6b 20 6d 61 79 20 69 6e 76 6f 6b 65 20  back may invoke 
c900: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
c910: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
c920: 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 62 75 74  ealloc()].** but
c930: 20 69 66 20 69 74 20 64 6f 65 73 2c 20 6e 6f 20   if it does, no 
c940: 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62  additional callb
c950: 61 63 6b 73 20 77 69 6c 6c 20 62 65 20 69 6e 76  acks will be inv
c960: 6f 6b 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 72  oked by.** the r
c970: 65 63 75 72 73 69 76 65 20 63 61 6c 6c 73 2e 0a  ecursive calls..
c980: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
c990: 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
c9a0: 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
c9b0: 77 6f 72 6b 73 20 62 79 20 72 65 67 69 73 74 65  works by registe
c9c0: 72 69 6e 67 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  ring.** a memory
c9d0: 20 61 6c 61 72 6d 20 61 74 20 74 68 65 20 73 6f   alarm at the so
c9e0: 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e  ft heap limit an
c9f0: 64 20 69 6e 76 6f 6b 69 6e 67 20 0a 2a 2a 20 5b  d invoking .** [
ca00: 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
ca10: 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 20 74 68 65  memory()] in the
ca20: 20 61 6c 61 72 6d 20 63 61 6c 6c 62 61 63 6b 2e   alarm callback.
ca30: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a    Application.**
ca40: 20 70 72 6f 67 72 61 6d 73 20 73 68 6f 75 6c 64   programs should
ca50: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
ca60: 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
ca70: 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d  _memory_alarm()]
ca80: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 65  .** interface be
ca90: 63 61 75 73 65 20 64 6f 69 6e 67 20 73 6f 20 77  cause doing so w
caa0: 69 6c 6c 20 69 6e 74 65 72 66 65 72 65 20 77 69  ill interfere wi
cab0: 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
cac0: 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
cad0: 69 74 28 29 5d 20 6d 6f 64 75 6c 65 2e 20 20 54  it()] module.  T
cae0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
caf0: 20 65 78 70 6f 73 65 64 0a 2a 2a 20 6f 6e 6c 79   exposed.** only
cb00: 20 73 6f 20 74 68 61 74 20 61 70 70 6c 69 63 61   so that applica
cb10: 74 69 6f 6e 73 20 63 61 6e 20 70 72 6f 76 69 64  tions can provid
cb20: 65 20 74 68 65 69 72 20 6f 77 6e 0a 2a 2a 20 61  e their own.** a
cb30: 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65  lternative imple
cb40: 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
cb50: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69  he SQLite core i
cb60: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
cb70: 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  th SQLITE_OMIT_M
cb80: 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
cb90: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
cba0: 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 0a 20  _memory_alarm(. 
cbb0: 20 76 6f 69 64 28 2a 78 43 61 6c 6c 62 61 63 6b   void(*xCallback
cbc0: 29 28 76 6f 69 64 20 2a 70 41 72 67 2c 20 73 71  )(void *pArg, sq
cbd0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 75 73 65 64  lite3_int64 used
cbe0: 2c 20 69 6e 74 20 4e 29 2c 0a 20 20 76 6f 69 64  , int N),.  void
cbf0: 20 2a 70 41 72 67 2c 0a 20 20 73 71 6c 69 74 65   *pArg,.  sqlite
cc00: 33 5f 69 6e 74 36 34 20 69 54 68 72 65 73 68 6f  3_int64 iThresho
cc10: 6c 64 0a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ld.);.../*.** CA
cc20: 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
cc30: 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
cc40: 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 2a  on Callbacks.***
cc50: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
cc60: 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74   registers a aut
cc70: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
cc80: 20 77 69 74 68 20 74 68 65 20 53 51 4c 69 74 65   with the SQLite
cc90: 20 6c 69 62 72 61 72 79 2e 20 20 0a 2a 2a 20 54   library.  .** T
cca0: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
ccb0: 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
ccc0: 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
ccd0: 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
cce0: 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
ccf0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
cd00: 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
cd10: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
cd20: 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
cd30: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
cd40: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
cd50: 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
cd60: 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70   At various.** p
cd70: 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
cd80: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
cd90: 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
cda0: 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
cdb0: 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
cdc0: 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
cdd0: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
cde0: 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
cdf0: 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
ce00: 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
ce10: 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61   allowed.  The a
ce20: 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
ce30: 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
ce40: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 74 6f  urn SQLITE_OK to
ce50: 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
ce60: 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
ce70: 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
ce80: 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
ce90: 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
cea0: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
ceb0: 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
cec0: 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
ced0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
cee0: 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
cef0: 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
cf00: 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
cf10: 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
cf20: 72 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 44 65 70  ror.  .**.** Dep
cf30: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 61 63  ending on the ac
cf40: 74 69 6f 6e 2c 20 74 68 65 20 5b 53 51 4c 49 54  tion, the [SQLIT
cf50: 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53  E_IGNORE] and [S
cf60: 51 4c 49 54 45 5f 44 45 4e 59 5d 20 72 65 74 75  QLITE_DENY] retu
cf70: 72 6e 0a 2a 2a 20 63 6f 64 65 73 20 6d 69 67 68  rn.** codes migh
cf80: 74 20 6d 65 61 6e 20 73 6f 6d 65 74 68 69 6e 67  t mean something
cf90: 20 64 69 66 66 65 72 65 6e 74 20 6f 72 20 74 68   different or th
cfa0: 65 79 20 6d 69 67 68 74 20 6d 65 61 6e 20 74 68  ey might mean th
cfb0: 65 20 73 61 6d 65 0a 2a 2a 20 74 68 69 6e 67 2e  e same.** thing.
cfc0: 20 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20    If the action 
cfd0: 69 73 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  is, for example,
cfe0: 20 74 6f 20 70 65 72 66 6f 72 6d 20 61 20 64 65   to perform a de
cff0: 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e 2c 0a 2a  lete opertion,.*
d000: 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 49  * then [SQLITE_I
d010: 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c 49  GNORE] and [SQLI
d020: 54 45 5f 44 45 4e 59 5d 20 62 6f 74 68 20 63 61  TE_DENY] both ca
d030: 75 73 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  use the statemen
d040: 74 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 0a 2a 2a  t compilation.**
d050: 20 74 6f 20 66 61 69 6c 20 77 69 74 68 20 61 6e   to fail with an
d060: 20 65 72 72 6f 72 2e 20 20 42 75 74 20 69 66 20   error.  But if 
d070: 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 74 6f  the action is to
d080: 20 72 65 61 64 20 61 20 73 70 65 63 69 66 69 63   read a specific
d090: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 72 6f 6d 20   column.** from 
d0a0: 61 20 73 70 65 63 69 66 69 63 20 74 61 62 6c 65  a specific table
d0b0: 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 44  , then [SQLITE_D
d0c0: 45 4e 59 5d 20 77 69 6c 6c 20 63 61 75 73 65 20  ENY] will cause 
d0d0: 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 74  the entire.** st
d0e0: 61 74 65 6d 65 6e 74 20 74 6f 20 66 61 69 6c 20  atement to fail 
d0f0: 62 75 74 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  but [SQLITE_IGNO
d100: 52 45 5d 20 77 69 6c 6c 20 63 61 75 73 65 20 61  RE] will cause a
d110: 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 62   NULL value to b
d120: 65 0a 2a 2a 20 72 65 61 64 20 69 6e 73 74 65 61  e.** read instea
d130: 64 20 6f 66 20 74 68 65 20 61 63 74 75 61 6c 20  d of the actual 
d140: 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a  column value..**
d150: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
d160: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
d170: 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
d180: 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
d190: 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72  ** the third par
d1a0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
d1b0: 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
d1c0: 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
d1d0: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
d1e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
d1f0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
d200: 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c  integer .** [SQL
d210: 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
d220: 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
d230: 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69  cifies the parti
d240: 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20  cular action.** 
d250: 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
d260: 2e 20 20 54 68 65 20 61 76 61 69 6c 61 62 6c 65  .  The available
d270: 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 61 72   action codes ar
d280: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50  e.** [SQLITE_COP
d290: 59 20 7c 20 64 6f 63 75 6d 65 6e 74 65 64 20 73  Y | documented s
d2a0: 65 70 61 72 61 74 65 6c 79 5d 2e 20 20 54 68 65  eparately].  The
d2b0: 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
d2c0: 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ixth.** paramete
d2d0: 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  rs to the callba
d2e0: 63 6b 20 61 72 65 20 73 74 72 69 6e 67 73 20 74  ck are strings t
d2f0: 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
d300: 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
d310: 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
d320: 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
d330: 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  zed..**.** An au
d340: 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
d350: 20 77 68 65 6e 20 70 72 65 70 61 72 69 6e 67 20   when preparing 
d360: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
d370: 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
d380: 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  .** source, to e
d390: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
d3a0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 64 6f  QL statements do
d3b0: 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
d3c0: 73 73 20 64 61 74 61 0a 2a 2a 20 74 68 61 74 20  ss data.** that 
d3d0: 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
d3e0: 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
d3f0: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
d400: 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78 65 63 75   try to.** execu
d410: 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
d420: 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
d430: 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
d440: 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
d450: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
d460: 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
d470: 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
d480: 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
d490: 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
d4a0: 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
d4b0: 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
d4c0: 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
d4d0: 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
d4e0: 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
d4f0: 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
d500: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
d510: 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
d520: 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
d530: 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
d540: 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
d550: 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
d560: 51 4c 20 69 73 20 62 65 69 6e 67 20 70 72 65 70  QL is being prep
d570: 61 72 65 64 20 74 68 61 74 20 64 69 73 61 6c 6c  ared that disall
d580: 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 0a 2a  ows everything.*
d590: 2a 20 65 78 63 65 70 74 20 53 45 4c 45 43 54 20  * except SELECT 
d5a0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 0a 2a 2a  statements.  .**
d5b0: 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  .** Only a singl
d5c0: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
d5d0: 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
d5e0: 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
d5f0: 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
d600: 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
d610: 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
d620: 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
d630: 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
d640: 75 73 20 63 61 6c 6c 2e 20 20 41 20 4e 55 4c 4c  us call.  A NULL
d650: 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e   authorizer mean
d660: 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72  s that no author
d670: 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
d680: 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
d690: 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74   The default aut
d6a0: 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e  horizer is NULL.
d6b0: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
d6c0: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
d6d0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
d6e0: 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 20  ked only during 
d6f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
d700: 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
d710: 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
d720: 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
d730: 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
d740: 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
d750: 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
d760: 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2f 0a  te3_step()]..*/.
d770: 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
d780: 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
d790: 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
d7a0: 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
d7b0: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
d7c0: 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
d7d0: 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
d7e0: 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
d7f0: 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
d800: 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
d810: 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
d820: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
d830: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
d840: 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
d850: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
d860: 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
d870: 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
d880: 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
d890: 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
d8a0: 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
d8b0: 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
d8c0: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
d8d0: 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
d8e0: 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
d8f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
d900: 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
d910: 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
d920: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
d930: 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
d940: 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ation..*/.#defin
d950: 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
d960: 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
d970: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
d980: 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
d990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
d9a0: 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
d9b0: 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
d9c0: 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
d9d0: 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
d9e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d9f0: 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
da00: 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
da10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
da20: 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
da30: 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
da40: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
da50: 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
da60: 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
da70: 6f 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20 53  orizer certain S
da80: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
da90: 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
daa0: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
dab0: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
dac0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
dad0: 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
dae0: 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
daf0: 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
db00: 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
db10: 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
db20: 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
db30: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
db40: 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
db50: 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
db60: 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
db70: 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
db80: 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
db90: 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a  ation is to be .
dba0: 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
dbb0: 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
dbc0: 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
dbd0: 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e authorization 
dbe0: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
dbf0: 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
dc00: 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
dc10: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
dc20: 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
dc30: 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
dc40: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
dc50: 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70  eter.  The 5th p
dc60: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
dc70: 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
dc80: 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
dc90: 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
dca0: 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
dcb0: 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66  p", .** etc.) if
dcc0: 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68   applicable.  Th
dcd0: 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
dce0: 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
dcf0: 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
dd00: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
dd10: 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
dd20: 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
dd30: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
dd40: 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
dd50: 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
dd60: 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
dd70: 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
dd80: 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f  ctly from .** to
dd90: 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
dda0: 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
ddb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
ddc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
ddd0: 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
dde0: 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
ddf0: 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
de00: 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
de10: 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
de20: 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
de30: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
de40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
de50: 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
de60: 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
de70: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
de80: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
de90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dea0: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
deb0: 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
dec0: 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
ded0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
dee0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
def0: 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
df00: 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
df10: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
df20: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
df30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
df40: 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
df50: 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
df60: 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
df70: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
df80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
df90: 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
dfa0: 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
dfb0: 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
dfc0: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
dfd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
dfe0: 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
dff0: 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
e000: 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
e010: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
e020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
e030: 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
e040: 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
e050: 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
e060: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
e070: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
e080: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
e090: 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
e0a0: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
e0b0: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
e0c0: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
e0d0: 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
e0e0: 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
e0f0: 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
e100: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
e110: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
e120: 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
e130: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
e140: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
e150: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
e160: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
e170: 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
e180: 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
e190: 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
e1a0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e1b0: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
e1c0: 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
e1d0: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
e1e0: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
e1f0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
e200: 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
e210: 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
e220: 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
e230: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
e240: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
e250: 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
e260: 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
e270: 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
e280: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
e290: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e2a0: 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
e2b0: 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
e2c0: 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
e2d0: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
e2e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e2f0: 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
e300: 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
e310: 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
e320: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
e330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e340: 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
e350: 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
e360: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
e370: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
e380: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e390: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
e3a0: 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
e3b0: 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
e3c0: 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
e3d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e3e0: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
e3f0: 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
e400: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
e410: 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
e420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
e430: 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
e440: 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
e450: 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
e460: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
e470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
e480: 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
e490: 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20     22   /* NULL 
e4a0: 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
e4b0: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
e4c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
e4d0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
e4e0: 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
e4f0: 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
e500: 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
e510: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
e520: 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
e530: 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
e540: 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
e550: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
e560: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
e570: 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
e580: 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
e590: 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
e5a0: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
e5b0: 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
e5c0: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
e5d0: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
e5e0: 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
e5f0: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
e600: 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
e610: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
e620: 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
e630: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
e640: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
e650: 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
e660: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
e670: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
e680: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
e690: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e6a0: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
e6b0: 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
e6c0: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
e6d0: 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
e6e0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
e6f0: 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
e700: 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
e710: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
e720: 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
e730: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
e740: 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
e750: 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
e760: 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20  * Function Name 
e770: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
e780: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e790: 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
e7a0: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
e7b0: 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
e7c0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
e7d0: 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
e7e0: 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
e7f0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
e800: 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
e810: 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
e820: 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
e830: 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
e840: 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
e850: 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
e860: 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
e870: 74 73 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  ts..** The callb
e880: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
e890: 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
e8a0: 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
e8b0: 76 6f 6b 65 64 0a 2a 2a 20 61 74 20 74 68 65 20  voked.** at the 
e8c0: 66 69 72 73 74 20 5b 73 71 6c 69 74 65 33 5f 73  first [sqlite3_s
e8d0: 74 65 70 28 29 5d 20 66 6f 72 20 74 68 65 20 65  tep()] for the e
e8e0: 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 20  valuation of an 
e8f0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
e900: 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
e910: 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
e920: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
e930: 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
e940: 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
e950: 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
e960: 73 68 65 73 20 61 6e 64 20 69 6e 63 6c 75 64 65  shes and include
e970: 73 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s.** information
e980: 20 6f 6e 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   on how long tha
e990: 74 20 73 74 61 74 65 6d 65 6e 74 20 72 61 6e 2e  t statement ran.
e9a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
e9b0: 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49  e3_profile() API
e9c0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
e9d0: 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
e9e0: 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20  ental and.** is 
e9f0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
ea00: 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
ea10: 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
ea20: 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
ea30: 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
ea40: 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  ar*), void*);.vo
ea50: 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
ea60: 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
ea70: 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
ea80: 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
ea90: 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
eaa0: 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
eab0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
eac0: 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
ead0: 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  backs.**.** This
eae0: 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75   routine configu
eaf0: 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  res a callback f
eb00: 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 20 70 72  unction - the pr
eb10: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
eb20: 2d 20 74 68 61 74 0a 2a 2a 20 69 73 20 69 6e 76  - that.** is inv
eb30: 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
eb40: 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
eb50: 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
eb60: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
eb70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
eb80: 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
eb90: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
eba0: 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
ebb0: 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74  for this .** int
ebc0: 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
ebd0: 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
ebe0: 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
ebf0: 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uery..**.** The 
ec00: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
ec10: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  k is invoked onc
ec20: 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69  e for every N vi
ec30: 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 6f 70  rtual machine op
ec40: 63 6f 64 65 73 2c 0a 2a 2a 20 77 68 65 72 65 20  codes,.** where 
ec50: 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
ec60: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
ec70: 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 70   function. The p
ec80: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
ec90: 0a 2a 2a 20 69 74 73 65 6c 66 20 69 73 20 69 64  .** itself is id
eca0: 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
ecb0: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
ecc0: 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
ecd0: 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 61   The fourth.** a
ece0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
ecf0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 76 6f  function is a vo
ed00: 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  id pointer passe
ed10: 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73  d to the progres
ed20: 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  s callback.** fu
ed30: 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65  nction each time
ed40: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a   it is invoked..
ed50: 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 20  **.** If a call 
ed60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
ed70: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
ed80: 65 70 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  ep()], or [sqlit
ed90: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a  e3_get_table()].
eda0: 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65  ** results in fe
edb0: 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64  wer than N opcod
edc0: 65 73 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  es being execute
edd0: 64 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67  d, then the prog
ede0: 72 65 73 73 20 0a 2a 2a 20 63 61 6c 6c 62 61 63  ress .** callbac
edf0: 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b  k is never invok
ee00: 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e 6c 79 20  ed..** .** Only 
ee10: 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
ee20: 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  s callback funct
ee30: 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
ee40: 74 65 72 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  tered for each.*
ee50: 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  * open database 
ee60: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 45 76 65  connection.  Eve
ee70: 72 79 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ry call to sqlit
ee80: 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
ee90: 6c 65 72 28 29 0a 2a 2a 20 6f 76 65 72 77 72 69  ler().** overwri
eea0: 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 73 20  tes the results 
eeb0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
eec0: 63 61 6c 6c 2e 0a 2a 2a 20 54 6f 20 72 65 6d 6f  call..** To remo
eed0: 76 65 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ve the progress 
eee0: 63 61 6c 6c 62 61 63 6b 20 61 6c 74 6f 67 65 74  callback altoget
eef0: 68 65 72 2c 20 70 61 73 73 20 4e 55 4c 4c 20 61  her, pass NULL a
ef00: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
ef10: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
ef20: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
ef30: 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
ef40: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
ef50: 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20   a result other 
ef60: 74 68 61 6e 20 30 2c 20 74 68 65 6e 20 74 68 65  than 0, then the
ef70: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 71 75 65   current .** que
ef80: 72 79 20 69 73 20 69 6d 6d 65 64 69 61 74 65 6c  ry is immediatel
ef90: 79 20 74 65 72 6d 69 6e 61 74 65 64 20 61 6e 64  y terminated and
efa0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 68   any database ch
efb0: 61 6e 67 65 73 20 72 6f 6c 6c 65 64 20 62 61 63  anges rolled bac
efc0: 6b 2e 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 61 69  k..** The contai
efd0: 6e 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ning [sqlite3_ex
efe0: 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
eff0: 73 74 65 70 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  step()], or.** [
f000: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
f010: 65 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  e()] call return
f020: 73 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  s SQLITE_INTERRU
f030: 50 54 2e 20 20 20 54 68 69 73 20 66 65 61 74 75  PT.   This featu
f040: 72 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  re.** can be use
f050: 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
f060: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  to implement the
f070: 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
f080: 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f 67 72 65 73   on a.** progres
f090: 73 20 64 69 61 6c 6f 67 20 62 6f 78 20 69 6e 20  s dialog box in 
f0a0: 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f 69 64 20 73  a GUI..*/.void s
f0b0: 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
f0c0: 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
f0d0: 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
f0e0: 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
f0f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
f100: 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
f110: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
f120: 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 74 68 65 20  .**.** Open the 
f130: 73 71 6c 69 74 65 20 64 61 74 61 62 61 73 65 20  sqlite database 
f140: 66 69 6c 65 20 22 66 69 6c 65 6e 61 6d 65 22 2e  file "filename".
f150: 20 20 54 68 65 20 22 66 69 6c 65 6e 61 6d 65 22    The "filename"
f160: 20 69 73 20 55 54 46 2d 38 0a 2a 2a 20 65 6e 63   is UTF-8.** enc
f170: 6f 64 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65  oded for [sqlite
f180: 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73  3_open()] and [s
f190: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
f1a0: 5d 20 61 6e 64 20 55 54 46 2d 31 36 20 65 6e 63  ] and UTF-16 enc
f1b0: 6f 64 65 64 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  oded.** in the n
f1c0: 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
f1d0: 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
f1e0: 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41 6e 20 5b  en16()]..** An [
f1f0: 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65  sqlite3*] handle
f200: 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20   is returned in 
f210: 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69  *ppDb, even.** i
f220: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
f230: 73 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61  s. If the databa
f240: 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 6f 72  se is opened (or
f250: 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
f260: 73 66 75 6c 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20  sfully,.** then 
f270: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
f280: 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69  eturned. Otherwi
f290: 73 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  se an error code
f2a0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68   is returned. Th
f2b0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
f2c0: 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
f2d0: 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
f2e0: 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
f2f0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
f300: 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
f310: 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
f320: 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e  on of the error.
f330: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
f340: 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
f350: 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
f360: 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
f370: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f380: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
f390: 65 6e 5f 76 32 28 29 5d 20 69 73 20 63 61 6c 6c  en_v2()] is call
f3a0: 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
f3b0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
f3c0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2e 0a  n16()] is used..
f3d0: 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
f3e0: 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
f3f0: 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
f400: 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
f410: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
f420: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
f430: 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  3*] handle shoul
f440: 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
f450: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 0a 2a   passing it to.*
f460: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  * [sqlite3_close
f470: 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
f480: 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
f490: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  d..**.** The [sq
f4a0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
f4b0: 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
f4c0: 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f   like [sqlite3_o
f4d0: 70 65 6e 28 29 5d 20 65 78 63 65 70 74 20 74 68  pen()] except th
f4e0: 61 74 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 74  at.** provides t
f4f0: 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
f500: 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
f510: 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 20  itional control 
f520: 6f 76 65 72 20 74 68 65 0a 2a 2a 20 6e 65 77 20  over the.** new 
f530: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f540: 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20  ion.  The flags 
f550: 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
f560: 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c   one of:.**.** <
f570: 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ol>.** <li>  [SQ
f580: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
f590: 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  LY].** <li>  [SQ
f5a0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
f5b0: 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  ITE].** <li>  [S
f5c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
f5d0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
f5e0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20  OPEN_CREATE].** 
f5f0: 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ol>.**.** The 
f600: 66 69 72 73 74 20 76 61 6c 75 65 20 6f 70 65 6e  first value open
f610: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 72  s the database r
f620: 65 61 64 2d 6f 6e 6c 79 2e 20 20 49 66 20 74 68  ead-only.  If th
f630: 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 0a  e database does.
f640: 2a 2a 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  ** not previousl
f650: 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
f660: 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
f670: 54 68 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f  The second optio
f680: 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64  n opens.** the d
f690: 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
f6a0: 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
f6b0: 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
f6c0: 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a  reading only if.
f6d0: 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ** if the file i
f6e0: 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
f6f0: 64 2e 20 20 49 6e 20 65 69 74 68 65 72 20 63 61  d.  In either ca
f700: 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
f710: 6d 75 73 74 20 61 6c 72 65 61 64 79 0a 2a 2a 20  must already.** 
f720: 65 78 69 73 74 20 6f 72 20 61 6e 20 65 72 72 6f  exist or an erro
f730: 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
f740: 54 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e  The third option
f750: 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62   opens the datab
f760: 61 73 65 0a 2a 2a 20 66 6f 72 20 72 65 61 64 69  ase.** for readi
f770: 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61  ng and writing a
f780: 6e 64 20 63 72 65 61 74 65 73 20 69 74 20 69 66  nd creates it if
f790: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
f7a0: 65 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54  eady exist..** T
f7b0: 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73  he third options
f7c0: 20 69 73 20 62 65 68 61 76 69 6f 72 20 74 68 61   is behavior tha
f7d0: 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
f7e0: 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
f7f0: 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  en()].** and [sq
f800: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
f810: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
f820: 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
f830: 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72  ry:", then an pr
f840: 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f  ivate.** in-memo
f850: 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63  ry database is c
f860: 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
f870: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73  onnection.  This
f880: 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61   in-memory.** da
f890: 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
f8a0: 73 68 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  sh when the data
f8b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
f8c0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
f8d0: 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  re.** version of
f8e0: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61   SQLite might ma
f8f0: 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
f900: 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
f910: 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62  enames.** that b
f920: 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
f930: 22 20 63 68 61 72 61 63 74 65 72 2e 20 20 49 74  " character.  It
f940: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
f950: 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20  that .** when a 
f960: 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
f970: 65 20 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65  e really does be
f980: 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20  gin with.** ":" 
f990: 74 68 61 74 20 79 6f 75 20 70 72 65 66 69 78 20  that you prefix 
f9a0: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
f9b0: 68 20 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b  h a pathname lik
f9c0: 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f  e "./" to.** avo
f9d0: 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
f9e0: 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
f9f0: 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
fa00: 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
fa10: 72 69 76 61 74 65 20 74 65 6d 70 6f 72 61 72 79  rivate temporary
fa20: 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
fa30: 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
fa40: 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76  ated.  This priv
fa50: 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
fa60: 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
fa70: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
fa80: 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
fa90: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
faa0: 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
fab0: 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
fac0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
fad0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
fae0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
faf0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
fb00: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
fb10: 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
fb20: 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74  g system .** int
fb30: 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
fb40: 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
fb50: 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
fb60: 73 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66  se.  If the.** f
fb70: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
fb80: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
fb90: 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
fba0: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
fbb0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 75 73  .** object is us
fbc0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
fbd0: 65 20 74 6f 20 77 69 6e 64 6f 77 73 20 75 73 65  e to windows use
fbe0: 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
fbf0: 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
fc00: 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
fc10: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69  ment.** of [sqli
fc20: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  te3_open()] and 
fc30: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
fc40: 28 29 5d 20 6d 75 73 74 20 62 65 20 55 54 46 2d  ()] must be UTF-
fc50: 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
fc60: 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
fc70: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
fc80: 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
fc90: 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
fca0: 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
fcb0: 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
fcc0: 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
fcd0: 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
fce0: 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  them into.** [sq
fcf0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
fd00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
fd10: 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2()]..*/.int sql
fd20: 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
fd30: 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
fd40: 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
fd50: 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
fd60: 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
fd70: 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
fd80: 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
fd90: 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
fda0: 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
fdb0: 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
fdc0: 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
fdd0: 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
fde0: 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
fdf0: 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
fe00: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
fe10: 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
fe20: 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
fe30: 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
fe40: 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
fe50: 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
fe60: 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
fe70: 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
fe80: 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
fe90: 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
fea0: 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
feb0: 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
fec0: 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
fed0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
fee0: 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
fef0: 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
ff00: 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
ff10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
ff20: 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
ff30: 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 54 68  essages.**.** Th
ff40: 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
ff50: 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
ff60: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
ff70: 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  c.** [SQLITE_OK 
ff80: 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f  | result code] o
ff90: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
ffa0: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
ffb0: 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20  result code].** 
ffc0: 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
ffd0: 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
ffe0: 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
fff0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
10000 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c   [sqlite3] handl
10010 65 20 27 64 62 27 2e 20 20 49 66 20 61 20 70 72  e 'db'.  If a pr
10020 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
10030 6c 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d  led but the.** m
10040 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
10050 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
10060 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
10070 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72  from sqlite3_err
10080 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64  code().** is und
10090 65 66 69 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54  efined. .**.** T
100a0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
100b0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
100c0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
100d0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 61 75  n English-langau
100e0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
100f0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
10100 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
10110 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73  TF8 or UTF16 res
10120 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65  pectively..** Me
10130 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
10140 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
10150 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
10160 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 20 54 68   internally.  Th
10170 65 20 0a 2a 2a 20 73 74 72 69 6e 67 20 6d 61 79  e .** string may
10180 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
10190 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
101a0 79 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  y subsequent cal
101b0 6c 73 20 74 6f 20 53 51 4c 69 74 65 0a 2a 2a 20  ls to SQLite.** 
101c0 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
101d0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 73  ons..**.** Calls
101e0 20 74 6f 20 6d 61 6e 79 20 73 71 6c 69 74 65 33   to many sqlite3
101f0 5f 2a 20 66 75 6e 63 74 69 6f 6e 73 20 73 65 74  _* functions set
10200 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
10210 61 6e 64 20 73 74 72 69 6e 67 20 72 65 74 75 72  and string retur
10220 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
10230 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
10240 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
10250 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
10260 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 28  errmsg16()].** (
10270 6f 76 65 72 77 72 69 74 69 6e 67 20 74 68 65 20  overwriting the 
10280 70 72 65 76 69 6f 75 73 20 76 61 6c 75 65 73 29  previous values)
10290 2e 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c  . Note that call
102a0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
102b0 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71  rcode()],.** [sq
102c0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
102d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
102e0 72 6d 73 67 31 36 28 29 5d 20 74 68 65 6d 73 65  rmsg16()] themse
102f0 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 66 66 65  lves do not affe
10300 63 74 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  ct the.** result
10310 73 20 6f 66 20 66 75 74 75 72 65 20 69 6e 76 6f  s of future invo
10320 63 61 74 69 6f 6e 73 2e 20 20 43 61 6c 6c 73 20  cations.  Calls 
10330 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  to API routines 
10340 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75  that do not retu
10350 72 6e 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63  rn.** an error c
10360 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73  ode (example: [s
10370 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
10380 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20  t()]) do not.** 
10390 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72  change the error
103a0 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62   code returned b
103b0 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20  y this routine. 
103c0 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74   Interfaces that
103d0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 61 73 73 6f   are.** not asso
103e0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70  ciated with a sp
103f0 65 63 69 66 69 63 20 64 61 74 61 62 61 73 65 20  ecific database 
10400 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 65 78 61 6d  connection (exam
10410 70 6c 65 73 3a 0a 2a 2a 20 5b 73 71 6c 69 74 65  ples:.** [sqlite
10420 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20  3_mprintf()] or 
10430 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
10440 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 20  shared_cache()] 
10450 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a  do not change.**
10460 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
10470 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69  .  .**.** Assumi
10480 6e 67 20 6e 6f 20 6f 74 68 65 72 20 69 6e 74 65  ng no other inte
10490 72 76 65 6e 69 6e 67 20 73 71 6c 69 74 65 33 5f  rvening sqlite3_
104a0 2a 20 41 50 49 20 63 61 6c 6c 73 20 61 72 65 20  * API calls are 
104b0 6d 61 64 65 2c 20 74 68 65 20 65 72 72 6f 72 0a  made, the error.
104c0 2a 2a 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64  ** code returned
104d0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
104e0 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
104f0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 72  with the same er
10500 72 6f 72 20 61 73 0a 2a 2a 20 74 68 65 20 73 74  ror as.** the st
10510 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
10520 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  y [sqlite3_errms
10530 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  g()] and [sqlite
10540 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
10550 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
10560 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
10570 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
10580 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
10590 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
105a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
105b0 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
105c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
105d0 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
105e0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 49 6e   Object.**.** In
105f0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
10600 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 20  bject represent 
10610 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
10620 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a 20  ments.  This.** 
10630 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
10640 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
10650 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
10660 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20  a .** "compiled 
10670 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
10680 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
10690 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a  tatement"..** .*
106a0 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
106b0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
106c0 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
106d0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
106e0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
106f0 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
10700 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
10710 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
10720 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
10730 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
10740 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
10750 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
10760 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  rs using.**     
10770 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
10780 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
10790 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d  nd_* interfaces]
107a0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
107b0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
107c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
107d0 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
107e0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
107f0 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
10800 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
10810 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
10820 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
10830 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
10840 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
10850 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
10860 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
10870 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
10880 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
10890 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
108a0 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
108b0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
108c0 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
108d0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
108e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
108f0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
10900 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
10910 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
10920 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
10930 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
10940 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  tement.**.** To 
10950 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
10960 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
10970 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
10980 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
10990 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
109a0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
109b0 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20  outines. .**.** 
109c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
109d0 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b 73  nt "db" is an [s
109e0 71 6c 69 74 65 33 20 7c 20 53 51 4c 69 74 65 20  qlite3 | SQLite 
109f0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d  database handle]
10a00 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72   .** obtained fr
10a10 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  om a prior call 
10a20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
10a30 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
10a40 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b  en_v2()].** or [
10a50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
10a60 5d 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  ]..** The second
10a70 20 61 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22   argument "zSql"
10a80 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
10a90 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
10aa0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
10ab0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
10ac0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
10ad0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
10ae0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
10af0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
10b00 66 61 63 65 73 20 75 73 65 73 20 55 54 46 2d 38  faces uses UTF-8
10b10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
10b20 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
10b30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
10b40 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
10b50 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  6..**.** If the 
10b60 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
10b70 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a  s less.** than z
10b80 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
10b90 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
10ba0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
10bb0 69 6e 61 74 6f 72 2e 20 20 49 66 0a 2a 2a 20 6e  inator.  If.** n
10bc0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
10bd0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
10be0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
10bf0 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73  ber of .** bytes
10c00 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
10c10 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20    When nByte is 
10c20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
10c30 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
10c40 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
10c50 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
10c60 20 63 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a   character or .*
10c70 2a 20 75 6e 74 69 6c 20 74 68 65 20 6e 42 79 74  * until the nByt
10c80 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
10c90 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
10ca0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20  ..**.** *pzTail 
10cb0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
10cc0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
10cd0 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
10ce0 6f 66 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  of the first.** 
10cf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
10d00 20 7a 53 71 6c 2e 20 20 54 68 69 73 20 72 6f 75   zSql.  This rou
10d10 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c  tine only compil
10d20 65 73 20 74 68 65 20 66 69 72 73 74 20 73 74 61  es the first sta
10d30 74 65 6d 65 6e 74 0a 2a 2a 20 69 6e 20 7a 53 71  tement.** in zSq
10d40 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
10d50 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
10d60 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  o what remains u
10d70 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
10d80 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
10d90 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
10da0 6f 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c  ompiled .** [sql
10db0 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
10dc0 73 74 61 74 65 6d 65 6e 74 20 73 74 72 75 63 74  statement struct
10dd0 75 72 65 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ure] that can be
10de0 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
10df0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
10e00 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72  ()].  Or if ther
10e10 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
10e20 70 70 53 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a  ppStmt may be.**
10e30 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49   set to NULL.  I
10e40 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
10e50 20 63 6f 6e 74 61 69 6e 65 64 20 6e 6f 20 53 51   contained no SQ
10e60 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
10e70 69 73 20 61 6e 64 0a 2a 2a 20 65 6d 70 74 79 20  is and.** empty 
10e80 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
10e90 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
10ea0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
10eb0 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  .  The calling.*
10ec0 2a 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  * procedure is r
10ed0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
10ee0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
10ef0 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
10f00 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  nt.** using [sql
10f10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
10f20 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
10f30 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
10f40 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
10f50 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
10f60 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
10f70 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 53 51  rwise an .** [SQ
10f80 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72  LITE_ERROR | err
10f90 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
10fa0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
10fb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
10fc0 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
10fd0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
10fe0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
10ff0 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
11000 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
11010 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
11020 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
11030 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
11040 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
11050 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
11060 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
11070 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68  uraged..** In th
11080 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
11090 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
110a0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
110b0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
110c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
110d0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
110e0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
110f0 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51   .** original SQ
11100 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
11110 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
11120 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
11130 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
11140 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  a differently in
11150 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a   two ways:.**.**
11160 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
11170 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
11180 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
11190 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
111a0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
111b0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
111c0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
111d0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
111e0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
111f0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
11200 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
11210 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
11220 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49  run it again.  I
11230 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
11240 20 63 68 61 6e 67 65 64 20 69 6e 20 61 20 77 61   changed in a wa
11250 79 0a 2a 2a 20 74 68 61 74 20 6d 61 6b 65 73 20  y.** that makes 
11260 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
11270 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
11280 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
11290 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
112a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
112b0 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
112c0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
112d0 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
112e0 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
112f0 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
11300 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
11310 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
11320 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
11330 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
11340 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
11350 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
11360 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
11370 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20  the text of the 
11380 70 61 72 73 69 6e 67 0a 2a 2a 20 65 72 72 6f 72  parsing.** error
11390 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
113a0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
113b0 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c  MA] return..** <
113c0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
113d0 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  ** When an error
113e0 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71   occurs, .** [sq
113f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
11400 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
11410 20 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a   the detailed .*
11420 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  * [SQLITE_ERROR 
11430 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  | result codes] 
11440 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
11450 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
11460 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
11470 5d 20 73 75 63 68 20 61 73 20 64 69 72 65 63 74  ] such as direct
11480 6c 79 2e 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63  ly..** The legac
11490 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
114a0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  hat [sqlite3_ste
114b0 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
114c0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
114d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
114e0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61  R] result code a
114f0 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76  nd you would hav
11500 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
11510 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nd call to.** [s
11520 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
11530 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
11540 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
11550 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
11560 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  blem..** With th
11570 65 20 22 76 32 22 20 70 72 65 70 61 72 65 20 69  e "v2" prepare i
11580 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
11590 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
115a0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
115b0 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d  s.** returned im
115c0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
115d0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
115e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
115f0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
11600 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
11610 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
11620 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
11630 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
11640 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
11650 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
11660 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
11670 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
11680 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
11690 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
116a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
116b0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
116c0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
116d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
116e0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
116f0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
11700 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
11710 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
11720 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
11730 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
11740 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
11750 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
11760 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
11770 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
11780 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
11790 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
117a0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
117b0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
117c0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
117d0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
117e0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
117f0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
11800 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
11810 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
11820 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
11830 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
11840 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
11850 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
11860 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
11870 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
11880 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
11890 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
118a0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
118b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
118c0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
118d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
118e0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
118f0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
11900 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
11910 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
11920 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
11930 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
11940 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
11950 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
11960 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
11970 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
11980 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
11990 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
119a0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
119b0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
119c0 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
119d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
119e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
119f0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
11a00 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
11a10 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
11a20 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
11a30 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
11a40 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
11a50 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
11a60 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
11a70 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
11a80 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
11a90 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
11aa0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
11ab0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
11ac0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
11ad0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
11ae0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
11af0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
11b00 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69  API3REF:  Dynami
11b10 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
11b20 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 53  e Object.**.** S
11b30 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
11b40 69 63 20 74 79 70 69 6e 67 20 66 6f 72 20 74 68  ic typing for th
11b50 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
11b60 65 73 2e 20 20 56 61 6c 75 65 73 20 63 61 6e 20  es.  Values can 
11b70 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c  .** be integers,
11b80 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
11b90 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
11ba0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
11bb0 20 20 57 68 65 6e 0a 2a 2a 20 70 61 73 73 69 6e    When.** passin
11bc0 67 20 61 72 6f 75 6e 64 20 76 61 6c 75 65 73 20  g around values 
11bd0 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 65 61 63 68  internally, each
11be0 20 76 61 6c 75 65 20 69 73 20 72 65 70 72 65 73   value is repres
11bf0 65 6e 74 65 64 20 61 73 0a 2a 2a 20 61 6e 20 69  ented as.** an i
11c00 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
11c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
11c20 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
11c30 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
11c40 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
11c50 20 43 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20   CAPI3REF:  SQL 
11c60 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
11c70 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
11c80 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
11c90 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
11ca0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
11cb0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
11cc0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
11cd0 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65  bject.  A pointe
11ce0 72 20 74 6f 20 73 75 63 68 20 61 6e 20 6f 62 6a  r to such an obj
11cf0 65 63 74 20 69 73 20 74 68 65 0a 2a 2a 20 66 69  ect is the.** fi
11d00 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
11d10 20 75 73 65 72 2d 64 65 66 69 6e 65 64 20 53 51   user-defined SQ
11d20 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a  L functions..*/.
11d30 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
11d40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
11d50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
11d60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11d70 20 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73    Binding Values
11d80 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
11d90 74 65 6d 65 6e 74 73 0a 2a 2a 0a 2a 2a 20 49 6e  tements.**.** In
11da0 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73   the SQL strings
11db0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
11dc0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
11dd0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
11de0 73 2c 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  s,.** one or mor
11df0 65 20 6c 69 74 65 72 61 6c 73 20 63 61 6e 20 62  e literals can b
11e00 65 20 72 65 70 6c 61 63 65 20 62 79 20 61 20 70  e replace by a p
11e10 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20  arameter in one 
11e20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 66 6f 72 6d  of these.** form
11e30 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
11e40 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
11e50 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
11e60 3a 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41  :AAA.** <li>  @A
11e70 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  AA.** <li>  $VVV
11e80 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
11e90 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  In the parameter
11ea0 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f   forms shown abo
11eb0 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74  ve NNN is an int
11ec0 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
11ed0 20 41 41 41 20 69 73 20 61 6e 20 61 6c 70 68 61   AAA is an alpha
11ee0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
11ef0 65 72 20 61 6e 64 20 56 56 56 20 69 73 20 61 20  er and VVV is a 
11f00 76 61 72 69 61 62 6c 65 20 6e 61 6d 65 20 61 63  variable name ac
11f10 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  cording.** to th
11f20 65 20 73 79 6e 74 61 78 20 72 75 6c 65 73 20 6f  e syntax rules o
11f30 66 20 74 68 65 20 54 43 4c 20 70 72 6f 67 72 61  f the TCL progra
11f40 6d 6d 69 6e 67 20 6c 61 6e 67 75 61 67 65 2e 0a  mming language..
11f50 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66  ** The values of
11f60 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
11f70 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
11f80 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
11f90 61 6d 65 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ames").** can be
11fa0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
11fb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
11fc0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
11fd0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
11fe0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11ff0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
12000 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
12010 20 61 6c 77 61 79 73 20 69 73 20 61 20 70 6f 69   always is a poi
12020 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
12030 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
12040 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
12050 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
12060 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
12070 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 54  its variants.  T
12080 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
12090 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
120a0 65 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  ex of the parame
120b0 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 20  ter to be set.  
120c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
120d0 74 65 72 20 68 61 73 0a 2a 2a 20 61 6e 20 69 6e  ter has.** an in
120e0 64 65 78 20 6f 66 20 31 2e 20 57 68 65 6e 20 74  dex of 1. When t
120f0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 20 70 61  he same named pa
12100 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
12110 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
12120 73 65 63 6f 6e 64 0a 2a 2a 20 61 6e 64 20 73 75  second.** and su
12130 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
12140 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
12150 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
12160 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
12170 6e 63 65 2e 20 20 54 68 65 20 69 6e 64 65 78 20  nce.  The index 
12180 66 6f 72 0a 2a 2a 20 6e 61 6d 65 64 20 70 61 72  for.** named par
12190 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
121a0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
121b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
121c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
121d0 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  me()] API if des
121e0 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78  ired.  The index
121f0 20 66 6f 72 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 70   for "?NNN".** p
12200 61 72 61 6d 65 74 65 73 20 69 73 20 74 68 65 20  arametes is the 
12210 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
12220 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d   The NNN value m
12230 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
12240 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65   and the compile
12250 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74  -time.** paramet
12260 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41  er SQLITE_MAX_VA
12270 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64  RIABLE_NUMBER (d
12280 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
12290 39 29 2e 0a 2a 2a 20 53 65 65 20 3c 61 20 68 72  9)..** See <a hr
122a0 65 66 3d 22 6c 69 6d 69 74 73 2e 68 74 6d 6c 22  ef="limits.html"
122b0 3e 6c 69 6d 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e  >limits.html</a>
122c0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
122d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
122e0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67  ** The third arg
122f0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
12300 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
12310 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
12320 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72  ** In those.** r
12330 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
12340 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
12350 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
12360 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
12370 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20  bytes.** in the 
12380 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
12390 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
123a0 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ue is the number
123b0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
123c0 0a 2a 2a 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  .** string, not 
123d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
123e0 61 72 61 63 74 65 72 73 2e 20 20 54 68 65 20 6e  aracters.  The n
123f0 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
12400 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  s does not inclu
12410 64 65 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  de the zero-term
12420 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e  inator at the en
12430 64 20 6f 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  d of strings..**
12440 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
12450 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
12460 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
12470 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
12480 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  s.** number of b
12490 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
124a0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
124b0 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ator..**.** The 
124c0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
124d0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
124e0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
124f0 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
12500 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
12510 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
12520 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
12530 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
12540 42 4c 4f 42 20 6f 72 0a 2a 2a 20 74 65 78 74 20  BLOB or.** text 
12550 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
12560 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
12570 74 2e 20 20 49 66 20 74 68 65 20 66 69 66 74 68  t.  If the fifth
12580 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
12590 0a 2a 2a 20 73 70 65 63 69 61 6c 20 76 61 6c 75  .** special valu
125a0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
125b0 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 69 62 72  ], then the libr
125c0 61 72 79 20 61 73 73 75 6d 65 73 20 74 68 61 74  ary assumes that
125d0 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e   the information
125e0 0a 2a 2a 20 69 73 20 69 6e 20 73 74 61 74 69 63  .** is in static
125f0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
12600 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
12610 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
12620 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 69 66 74    If the.** fift
12630 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
12640 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
12650 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
12660 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  n SQLite makes i
12670 74 73 0a 2a 2a 20 6f 77 6e 20 70 72 69 76 61 74  ts.** own privat
12680 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
12690 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
126a0 62 65 66 6f 72 65 20 74 68 65 20 73 71 6c 69 74  before the sqlit
126b0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 72  e3_bind_*().** r
126c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
126d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
126e0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
126f0 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
12700 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
12710 20 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   n that.** is fi
12720 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e  lled with zeros.
12730 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65    A zeroblob use
12740 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
12750 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
12760 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
12770 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20  o hold it size) 
12780 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
12790 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
127a0 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
127b0 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
127c0 61 73 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73  as place-holders
127d0 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
127e0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
127f0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
12800 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
12810 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
12820 65 6d 65 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20  ement BLOB I/O] 
12830 72 6f 75 74 69 6e 65 73 2e 20 20 41 20 6e 65 67  routines.  A neg
12840 61 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65 20 66  ative.** value f
12850 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
12860 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
12870 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
12880 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12890 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
128a0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
128b0 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69  d after.** [sqli
128c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
128d0 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61  ] (and its varia
128e0 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  nts) or [sqlite3
128f0 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a  _reset()] and.**
12900 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
12910 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e  _step()]..** Bin
12920 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
12930 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
12940 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
12950 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75  outine..** Unbou
12960 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
12970 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
12980 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
12990 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
129a0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
129b0 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20  n success or an 
129c0 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a  error code if.**
129d0 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
129e0 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52  rong.  [SQLITE_R
129f0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
12a00 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
12a10 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
12a20 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53  ut of range.  [S
12a30 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
12a40 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
12a50 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51  oc fails..** [SQ
12a60 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 69 73 20  LITE_MISUSE] is 
12a70 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73  returned if thes
12a80 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
12a90 61 6c 6c 65 64 20 6f 6e 20 61 20 76 69 72 74 75  alled on a virtu
12aa0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 74 68  al.** machine th
12ab0 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20  at is the wrong 
12ac0 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68  state or which h
12ad0 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  as already been 
12ae0 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f 0a 69 6e  finalized..*/.in
12af0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
12b00 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
12b10 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
12b20 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
12b30 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
12b40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
12b50 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
12b60 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
12b70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
12b80 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
12b90 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
12ba0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
12bb0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
12bc0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
12bd0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
12be0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
12bf0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
12c00 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
12c10 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
12c20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
12c30 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
12c40 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
12c50 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
12c60 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
12c70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
12c80 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
12c90 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
12ca0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
12cb0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
12cc0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
12cd0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
12ce0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
12cf0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
12d00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
12d10 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
12d20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
12d30 6d 62 65 72 20 4f 66 20 48 6f 73 74 20 50 61 72  mber Of Host Par
12d40 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 52 65  ameters.**.** Re
12d50 74 75 72 6e 20 74 68 65 20 6c 61 72 67 65 73 74  turn the largest
12d60 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
12d70 69 6e 64 65 78 20 69 6e 20 74 68 65 20 70 72 65  index in the pre
12d80 63 6f 6d 70 69 6c 65 64 20 73 74 61 74 65 6d 65  compiled stateme
12d90 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 61 73 20 74  nt given.** as t
12da0 68 65 20 61 72 67 75 6d 65 6e 74 2e 20 20 57 68  he argument.  Wh
12db0 65 6e 20 74 68 65 20 68 6f 73 74 20 70 61 72 61  en the host para
12dc0 6d 65 74 65 72 73 20 61 72 65 20 6f 66 20 74 68  meters are of th
12dd0 65 20 66 6f 72 6d 73 20 6c 69 6b 65 20 22 3a 41  e forms like ":A
12de0 41 41 22 0a 2a 2a 20 6f 72 20 22 3f 22 2c 20 74  AA".** or "?", t
12df0 68 65 6e 20 74 68 65 79 20 61 72 65 20 61 73 73  hen they are ass
12e00 69 67 6e 65 64 20 73 65 71 75 65 6e 74 69 61 6c  igned sequential
12e10 20 69 6e 63 72 65 61 73 69 6e 67 20 6e 75 6d 62   increasing numb
12e20 65 72 73 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ers beginning.**
12e30 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f 20 74 68   with one, so th
12e40 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
12e50 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
12e60 66 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 48  f parameters.  H
12e70 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20 74 68 65  owever.** if the
12e80 20 73 61 6d 65 20 68 6f 73 74 20 70 61 72 61 6d   same host param
12e90 65 74 65 72 20 6e 61 6d 65 20 69 73 20 75 73 65  eter name is use
12ea0 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
12eb0 2c 20 65 61 63 68 20 6f 63 63 75 72 72 61 6e 63  , each occurranc
12ec0 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20 74 68  e.** is given th
12ed0 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 2c 20 73  e same number, s
12ee0 6f 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  o the value retu
12ef0 72 6e 65 64 20 69 6e 20 74 68 61 74 20 63 61 73  rned in that cas
12f00 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 0a  e is the number.
12f10 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20 68 6f 73  ** of unique hos
12f20 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
12f30 73 2e 20 20 49 66 20 68 6f 73 74 20 70 61 72 61  s.  If host para
12f40 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
12f50 72 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 61 72 65  rm "?NNN".** are
12f60 20 75 73 65 64 20 28 77 68 65 72 65 20 4e 4e 4e   used (where NNN
12f70 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 20   is an integer) 
12f80 74 68 65 6e 20 74 68 65 72 65 20 6d 69 67 68 74  then there might
12f90 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 0a   be gaps in the.
12fa0 2a 2a 20 6e 75 6d 62 65 72 69 6e 67 20 61 6e 64  ** numbering and
12fb0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
12fc0 6e 65 64 20 62 79 20 74 68 69 73 20 69 6e 74 65  ned by this inte
12fd0 72 66 61 63 65 20 69 73 20 74 68 65 20 69 6e 64  rface is the ind
12fe0 65 78 20 6f 66 20 74 68 65 0a 2a 2a 20 68 6f 73  ex of the.** hos
12ff0 74 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68  t parameter with
13000 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64   the largest ind
13010 65 78 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ex value..**.** 
13020 54 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  The prepared sta
13030 74 65 6d 65 6e 74 20 6d 75 73 74 20 6e 6f 74 20  tement must not 
13040 62 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  be [sqlite3_fina
13050 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
13060 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  ].** prior to th
13070 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
13080 6e 6e 69 6e 67 2e 20 20 4f 74 68 65 72 77 69 73  nning.  Otherwis
13090 65 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  e the results ar
130a0 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 61  e undefined.** a
130b0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
130c0 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20  sirable..*/.int 
130d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
130e0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
130f0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
13100 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
13110 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
13120 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 54 68 69  ameter.**.** Thi
13130 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
13140 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
13150 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
13160 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e  -th parameter in
13170 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   a .** [sqlite3_
13180 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
13190 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 48  statement]..** H
131a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 6f  ost parameters o
131b0 66 20 74 68 65 20 66 6f 72 6d 20 22 3a 41 41 41  f the form ":AAA
131c0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
131d0 24 56 56 56 22 20 68 61 76 65 20 61 20 6e 61 6d  $VVV" have a nam
131e0 65 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 74 68  e.** which is th
131f0 65 20 73 74 72 69 6e 67 20 22 3a 41 41 41 22 20  e string ":AAA" 
13200 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 56  or "@AAA" or "$V
13210 56 56 22 2e 20 20 0a 2a 2a 20 49 6e 20 6f 74 68  VV".  .** In oth
13220 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
13230 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
13240 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73 20 69 6e   or "@".** is in
13250 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
13260 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50  f the name..** P
13270 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
13280 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f 4e   form "?" or "?N
13290 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  NN" have no name
132a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
132b0 74 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  t bound paramete
132c0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
132d0 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
132e0 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e  * If the value n
132f0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
13300 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20   or if the n-th 
13310 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 61 6d  parameter is nam
13320 65 6c 65 73 73 2c 0a 2a 2a 20 74 68 65 6e 20 4e  eless,.** then N
13330 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
13340 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73    The returned s
13350 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
13360 69 6e 20 74 68 65 0a 2a 2a 20 55 54 46 2d 38 20  in the.** UTF-8 
13370 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
13380 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
13390 65 74 65 72 20 77 61 73 20 6f 72 69 67 69 6e 61  eter was origina
133a0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lly specified.**
133b0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
133c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
133d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
133e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
133f0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
13400 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
13410 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
13420 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
13430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13440 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
13450 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
13460 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 54  ven Name.**.** T
13470 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
13480 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
13490 20 61 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   a host paramete
134a0 72 20 77 69 74 68 20 74 68 65 20 67 69 76 65 6e  r with the given
134b0 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 6e 61   name..** The na
134c0 6d 65 20 6d 75 73 74 20 6d 61 74 63 68 20 65 78  me must match ex
134d0 61 63 74 6c 79 2e 20 20 49 66 20 6e 6f 20 70 61  actly.  If no pa
134e0 72 61 6d 65 74 65 72 20 77 69 74 68 20 74 68 65  rameter with the
134f0 20 67 69 76 65 6e 20 6e 61 6d 65 20 69 73 20 0a   given name is .
13500 2a 2a 20 66 6f 75 6e 64 2c 20 72 65 74 75 72 6e  ** found, return
13510 20 30 2e 20 20 50 61 72 61 6d 65 74 65 72 20 6e   0.  Parameter n
13520 61 6d 65 73 20 6d 75 73 74 20 62 65 20 55 54 46  ames must be UTF
13530 38 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  8..*/.int sqlite
13540 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
13550 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
13560 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
13570 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
13580 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
13590 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
135a0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
135b0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74  ement.**.** Cont
135c0 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
135d0 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
135e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
135f0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73   does not.** res
13600 65 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  et the [sqlite3_
13610 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
13620 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b  ings] on a .** [
13630 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
13640 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13650 74 5d 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f  t].  Use this ro
13660 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65  utine to.** rese
13670 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
13680 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
13690 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
136a0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
136b0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
136c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
136d0 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
136e0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
136f0 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
13700 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
13710 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
13720 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
13730 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
13740 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65  3_stmt | compile
13750 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d  d SQL statement]
13760 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  . This routine r
13770 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70  eturns 0.** if p
13780 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73  Stmt is an SQL s
13790 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
137a0 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
137b0 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d  ta (for .** exam
137c0 70 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a  ple an UPDATE)..
137d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
137e0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
137f0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
13800 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13810 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
13820 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
13830 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
13840 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
13850 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
13860 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
13870 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
13880 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53  esult set of a S
13890 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
138a0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f    The sqlite3_co
138b0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
138c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
138d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
138e0 55 54 46 38 20 73 74 72 69 6e 67 20 61 6e 64 20  UTF8 string and 
138f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
13900 61 6d 65 31 36 28 29 0a 2a 2a 20 72 65 74 75 72  ame16().** retur
13910 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
13920 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20  a UTF16 string. 
13930 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
13940 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
13950 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
13960 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13970 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  t] that implemen
13980 74 73 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  ts the SELECT st
13990 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  atement..** The 
139a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
139b0 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e   is the column n
139c0 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
139d0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a  -most column is.
139e0 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  ** number 0..**.
139f0 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
13a00 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
13a10 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
13a20 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ther the .** [sq
13a30 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
13a40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
13a50 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
13a60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
13a70 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69  ze()].** or unti
13a80 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
13a90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
13aa0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
13ab0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
13ac0 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
13ad0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  column..**.** If
13ae0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
13af0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
13b00 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
13b10 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
13b20 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
13b30 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
13b40 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
13b50 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
13b60 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
13b70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   is returned..*/
13b80 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
13b90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
13ba0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
13bb0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
13bc0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
13bd0 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
13be0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
13bf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13c00 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
13c10 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
13c20 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  lt.**.** These r
13c30 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
13c40 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
13c50 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e  mine what column
13c60 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c   of what.** tabl
13c70 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62  e in which datab
13c80 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20  ase a result of 
13c90 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
13ca0 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a  nt comes from..*
13cb0 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
13cc0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
13cd0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
13ce0 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
13cf0 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
13d00 38 20 6f 72 20 55 54 46 31 36 20 73 74 72 69 6e  8 or UTF16 strin
13d10 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73  g.  The _databas
13d20 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
13d30 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
13d40 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
13d50 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
13d60 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
13d70 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
13d80 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
13d90 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
13da0 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  mn name..** The 
13db0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
13dc0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a 2a  is valid until.*
13dd0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * the [sqlite3_s
13de0 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73  tmt | prepared s
13df0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
13e00 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20  troyed using.** 
13e10 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
13e20 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
13e30 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
13e40 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
13e50 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
13e60 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
13e70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
13e80 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
13e90 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
13ea0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
13eb0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
13ec0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
13ed0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  mn..**.** The fi
13ee0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
13ef0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
13f00 6c 6c 73 20 69 73 20 61 20 0a 2a 2a 20 5b 73 71  lls is a .** [sq
13f10 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d  lite3_stmt | com
13f20 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
13f30 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66  ent]..** These f
13f40 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
13f50 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
13f60 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  t the Nth column
13f70 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
13f80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
13f90 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
13fa0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
13fb0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49  rgument..**.** I
13fc0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
13fd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
13fe0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
13ff0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f   expression.** o
14000 72 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  r subquery and i
14010 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
14020 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
14030 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
14040 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c  s.** return NULL
14050 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65  . Otherwise, the
14060 79 20 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a  y return the .**
14070 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
14080 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
14090 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
140a0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
140b0 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73  lt.** column was
140c0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
140d0 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61  .**.** As with a
140e0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
140f0 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74  APIs, those post
14100 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20  fixed with "16" 
14110 72 65 74 75 72 6e 20 55 54 46 2d 31 36 0a 2a 2a  return UTF-16.**
14120 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
14130 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  , the other func
14140 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
14150 2d 38 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  -8..**.** These 
14160 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
14170 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
14180 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
14190 6c 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  led with the .**
141a0 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
141b0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70  OLUMN_METADATA p
141c0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
141d0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ol defined..**.*
141e0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
141f0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
14200 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
14210 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
14220 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
14230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14240 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
14250 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
14260 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
14270 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
14280 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
14290 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
142a0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
142b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
142c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
142d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
142e0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
142f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
14300 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
14310 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
14320 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
14330 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
14340 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
14350 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
14360 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
14370 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
14380 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
14390 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
143a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
143b0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
143c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
143d0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
143e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
143f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14400 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
14410 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
14420 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ult.**.** The fi
14430 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
14440 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
14450 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20   | compiled SQL 
14460 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a 20  statement]. .** 
14470 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
14480 74 20 69 73 20 61 20 53 45 4c 45 43 54 20 73 74  t is a SELECT st
14490 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
144a0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
144b0 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  e .** returned r
144c0 65 73 75 6c 74 20 73 65 74 20 20 6f 66 20 74 68  esult set  of th
144d0 61 74 20 53 45 4c 45 43 54 20 69 73 20 61 20 74  at SELECT is a t
144e0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
144f0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
14500 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
14510 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
14520 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
14530 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
14540 72 65 74 75 72 6e 65 64 2e 20 49 66 20 74 68 65  returned. If the
14550 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
14560 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
14570 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
14580 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
14590 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
145a0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
145b0 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
145c0 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
145d0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20   UTF-8 encoded. 
145e0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 0a  For example, in.
145f0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
14600 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
14610 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
14620 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
14630 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   And the followi
14640 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  ng statement com
14650 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
14660 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
14670 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68  ROM t1;.**.** Th
14680 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
14690 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
146a0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
146b0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
146c0 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  .** result colum
146d0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
146e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
146f0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
14700 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d  t column.** (i==
14710 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  0)..**.** SQLite
14720 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
14730 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
14740 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
14750 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
14760 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
14770 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
14780 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
14790 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
147a0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
147b0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
147c0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
147d0 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
147e0 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
147f0 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
14800 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
14810 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20  tatic.  Type.** 
14820 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
14830 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
14840 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
14850 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
14860 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
14870 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
14880 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
14890 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
148a0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  pe(sqlite3_stmt 
148b0 2a 2c 20 69 6e 74 20 69 29 3b 0a 63 6f 6e 73 74  *, int i);.const
148c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
148d0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
148e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
148f0 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50  nt);../* .** CAP
14900 49 33 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65  I3REF:  Evaluate
14910 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
14920 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e  t.**.** After an
14930 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
14940 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20   SQL statement] 
14950 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
14960 64 20 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a  d with a call.**
14970 20 74 6f 20 65 69 74 68 65 72 20 5b 73 71 6c 69   to either [sqli
14980 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
14990 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
149a0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
149b0 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68   to one of.** th
149c0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
149d0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
149e0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
149f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
14a00 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 66  ,.** then this f
14a10 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
14a20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
14a30 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
14a40 75 61 74 65 20 74 68 65 20 0a 2a 2a 20 73 74 61  uate the .** sta
14a50 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
14a60 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
14a70 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
14a80 73 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  s sqlite3_step()
14a90 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
14aa0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
14ab0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
14ac0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
14ad0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
14ae0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
14af0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
14b00 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
14b10 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
14b20 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
14b30 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
14b40 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
14b50 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
14b60 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
14b70 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
14b80 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
14b90 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
14ba0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
14bb0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
14bc0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
14bd0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
14be0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
14bf0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  rted..**.** In t
14c00 68 65 20 6c 61 67 61 63 79 20 69 6e 74 65 72 66  he lagacy interf
14c10 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
14c20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
14c30 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
14c40 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  Y], .** [SQLITE_
14c50 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
14c60 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
14c70 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
14c80 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68  MISUSE]..** With
14c90 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
14ca0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
14cb0 6f 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  other [SQLITE_OK
14cc0 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a   | result code].
14cd0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
14ce0 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
14cf0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
14d00 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
14d10 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a  ed as.** well..*
14d20 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  *.** [SQLITE_BUS
14d30 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
14d40 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
14d50 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
14d60 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
14d70 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
14d80 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
14d90 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74   job.  If the st
14da0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d  atement is a COM
14db0 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  MIT.** or occurs
14dc0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
14dd0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
14de0 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
14df0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
14e00 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
14e10 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
14e20 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20  ot a COMMIT and 
14e30 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a  occurs within a.
14e40 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
14e50 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
14e60 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
14e70 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
14e80 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
14e90 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  nuing..**.** [SQ
14ea0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
14eb0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
14ec0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
14ed0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
14ee0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
14ef0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
14f00 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
14f10 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
14f20 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
14f30 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
14f40 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
14f50 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
14f60 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
14f70 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
14f80 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
14f90 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ate..**.** If th
14fa0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
14fb0 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
14fc0 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
14fd0 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54   then .** [SQLIT
14fe0 45 5f 52 4f 57 5d 20 69 73 20 72 65 74 75 72 6e  E_ROW] is return
14ff0 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
15000 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
15010 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70  s ready.** for p
15020 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
15030 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
15040 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
15050 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  sed using.** the
15060 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
15070 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63  _int | column ac
15080 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
15090 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
150a0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
150b0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
150c0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
150d0 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c  ata..** .** [SQL
150e0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
150f0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
15100 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
15110 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
15120 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
15130 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
15140 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
15150 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
15160 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
15170 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
15180 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
15190 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
151a0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
151b0 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63  * With the legac
151c0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
151d0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
151e0 6f 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65  or code (example
151f0 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  :.** [SQLITE_INT
15200 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
15210 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
15220 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
15230 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
15240 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
15250 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
15260 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
15270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
15280 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
15290 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65  tement].  In the
152a0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
152b0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
152c0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
152d0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
152e0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
152f0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
15300 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
15310 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
15320 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
15330 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
15340 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
15350 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
15360 6f 6e 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  on a [sqlite3_st
15370 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
15380 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
15390 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
153a0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
153b0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
153c0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
153d0 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73  had .** previous
153e0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
153f0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
15400 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
15410 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
15420 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
15430 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
15440 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
15450 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
15460 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
15470 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
15480 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
15490 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
154a0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
154b0 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67  b>.** In the leg
154c0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 0a  acy interface, .
154d0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  ** the sqlite3_s
154e0 74 65 70 28 29 20 41 50 49 20 61 6c 77 61 79 73  tep() API always
154f0 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
15500 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a  ic error code,.*
15510 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
15520 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  , following any 
15530 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
15540 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
15550 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  * and [SQLITE_MI
15560 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
15570 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72   call [sqlite3_r
15580 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
15590 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
155a0 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
155b0 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 73  ind one of the s
155c0 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53 51 4c 49  pecific.** [SQLI
155d0 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c  TE_ERROR | resul
155e0 74 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  t codes] that be
155f0 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
15600 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
15610 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
15620 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
15630 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
15640 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
15650 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
15660 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
15670 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
15680 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
15690 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
156a0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
156b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
156c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
156d0 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
156e0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
156f0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
15700 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
15710 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
15720 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f   then the .** mo
15730 72 65 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c  re specific [SQL
15740 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75  ITE_ERROR | resu
15750 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  lt codes] are re
15760 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
15770 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
15780 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
15790 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
157a0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
157b0 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
157c0 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
157d0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
157e0 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a 2a 2a 20  CAPI3REF:.**.** 
157f0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
15800 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74  r of values in t
15810 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
15820 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
15830 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  ..**.** After a 
15840 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
15850 5f 73 74 65 70 28 29 5d 20 74 68 61 74 20 72 65  _step()] that re
15860 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f  turns [SQLITE_RO
15870 57 5d 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  W], this routine
15880 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
15890 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 61  the same value a
158a0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  s the [sqlite3_c
158b0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 20 66  olumn_count()] f
158c0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41 66 74 65  unction..** Afte
158d0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
158e0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
158f0 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  an [SQLITE_DONE]
15900 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
15910 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c 49 54 45   or.** a [SQLITE
15920 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63  _ERROR | error c
15930 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f 72 65 20  ode], or before 
15940 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
15950 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 63 61   has been .** ca
15960 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 73 71 6c  lled on the [sql
15970 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
15980 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
15990 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74 69  for the first ti
159a0 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  me,.** this rout
159b0 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
159c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
159d0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
159e0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
159f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15a00 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
15a10 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a 2a 20 45  atatypes.**.** E
15a20 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
15a30 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
15a40 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
15a50 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
15a60 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
15a70 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
15a80 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
15a90 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
15aa0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
15ab0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
15ac0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
15ad0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
15ae0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
15af0 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
15b00 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
15b10 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
15b20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
15b30 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
15b40 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
15b50 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
15b60 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
15b70 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
15b80 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
15b90 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
15ba0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
15bb0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
15bc0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
15bd0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
15be0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e  e SQLITE3_TEXT n
15bf0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
15c00 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
15c10 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
15c20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
15c30 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
15c40 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
15c50 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
15c60 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
15c70 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
15c80 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
15c90 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
15ca0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
15cb0 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
15cc0 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
15cd0 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
15ce0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73  API3REF: Results
15cf0 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
15d00 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  uery.**.** These
15d10 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
15d20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
15d30 75 74 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63  ut.** a single c
15d40 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
15d50 72 65 6e 74 20 72 65 73 75 6c 74 20 72 6f 77 20  rent result row 
15d60 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20  of a query.  In 
15d70 65 76 65 72 79 0a 2a 2a 20 63 61 73 65 20 74 68  every.** case th
15d80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15d90 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
15da0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
15db0 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61  3_stmt | SQL sta
15dc0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
15dd0 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61 74  being.** evaluat
15de0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
15df0 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 61 73  _stmt*] that was
15e00 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 0a   returned from .
15e10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
15e20 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
15e30 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
15e40 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65 63  ) and.** the sec
15e50 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
15e60 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
15e70 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
15e80 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a  h information .*
15e90 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
15ea0 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 2d  rned.  The left-
15eb0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
15ec0 68 65 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a  he result set.**
15ed0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
15ee0 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65   0..**.** If the
15ef0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
15f00 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
15f10 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
15f20 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
15f30 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e  ** the column in
15f40 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
15f50 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
15f60 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a  is undefined. .*
15f70 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
15f80 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
15f90 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
15fa0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
15fb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
15fc0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
15fd0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
15fe0 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
15ff0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
16000 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
16010 61 6c 69 7a 65 28 29 5d 20 68 61 73 20 62 65 65  alize()] has bee
16020 6e 20 63 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  n call subsequen
16030 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
16040 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
16050 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
16060 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
16070 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
16080 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
16090 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
160a0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
160b0 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
160c0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
160d0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
160e0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
160f0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
16100 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
16110 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
16120 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
16130 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
16140 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
16150 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
16160 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
16170 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
16180 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
16190 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
161a0 65 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a 2a  e undefined.  .*
161b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
161c0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
161d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 0a  outine returns .
161e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
161f0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
16200 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
16210 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
16220 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
16230 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75  olumn.  The retu
16240 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
16250 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
16260 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
16270 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
16280 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
16290 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
162a0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
162b0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
162c0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
162d0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
162e0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
162f0 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
16300 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
16310 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
16320 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
16330 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
16340 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
16350 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
16360 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
16370 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
16380 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
16390 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
163a0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
163b0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
163c0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
163d0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
163e0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
163f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
16400 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
16410 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
16420 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
16430 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a  lumn_bytes() .**
16440 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
16450 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
16460 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
16470 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
16480 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
16490 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
164a0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
164b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
164c0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
164d0 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
164e0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
164f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
16500 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  es..** If the re
16510 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
16520 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
16530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
16540 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
16550 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
16560 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
16570 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
16580 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
16590 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
165a0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
165b0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54  hat string..** T
165c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
165d0 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
165e0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
165f0 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e  inator at the en
16600 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
16610 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79  ng.  For clarity
16620 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  : the value retu
16630 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62  rned is the numb
16640 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
16650 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
16660 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
16670 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
16680 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e  * Strings return
16690 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
166a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
166b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
166c0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
166d0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 73 74 72   zero-length str
166e0 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
166f0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64   zero terminated
16700 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a  .  The return.**
16710 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
16720 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
16730 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
16740 67 74 68 20 62 6c 6f 62 20 69 73 20 61 6e 20 61  gth blob is an a
16750 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e  rbitrary.** poin
16760 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76  ter, possibly ev
16770 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
16780 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
16790 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
167a0 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73  s16() routine is
167b0 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69   similar to sqli
167c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
167d0 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73  ().** but leaves
167e0 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55   the result in U
167f0 54 46 2d 31 36 20 69 6e 73 74 65 61 64 20 6f 66  TF-16 instead of
16800 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65   UTF-8.  .** The
16810 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
16820 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
16830 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
16840 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
16850 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
16860 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
16870 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
16880 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ate.  For.** exa
16890 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
168a0 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
168b0 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
168c0 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
168d0 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
168e0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
168f0 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
16900 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20 74  ternally to do t
16910 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  he conversion.**
16920 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
16930 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
16940 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
16950 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68 61   conversions tha
16960 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c 69 65 64  t.** are applied
16970 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
16980 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
16990 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
169a0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
169b0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
169c0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
169d0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
169e0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
169f0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
16a00 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
16a10 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
16a20 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
16a30 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
16a40 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
16a50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
16a60 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
16a70 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
16a80 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
16a90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
16aa0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
16ab0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
16ac0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
16ad0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
16ae0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
16af0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
16b00 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
16b10 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
16b20 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
16b30 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
16b40 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
16b50 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
16b60 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
16b70 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
16b80 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66    <td> Same as f
16b90 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  or INTEGER->TEXT
16ba0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
16bb0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
16bc0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
16bd0 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
16be0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
16bf0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
16c00 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
16c10 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
16c20 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
16c30 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
16c40 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
16c50 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
16c60 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
16c70 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
16c80 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
16c90 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
16ca0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
16cb0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
16cc0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
16cd0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
16ce0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
16cf0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
16d00 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
16d10 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
16d20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
16d30 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
16d40 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
16d50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
16d60 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
16d70 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
16d80 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
16d90 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
16da0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
16db0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
16dc0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
16dd0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
16de0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
16df0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
16e00 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
16e10 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
16e20 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
16e30 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
16e40 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
16e50 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
16e60 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
16e70 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
16e80 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
16e90 74 73 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c  ts.** on equaval
16ea0 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
16eb0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
16ec0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
16ed0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
16ee0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
16ef0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
16f00 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
16f10 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
16f20 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
16f30 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
16f40 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
16f50 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
16f60 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
16f70 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
16f80 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
16f90 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
16fa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
16fb0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
16fc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
16fd0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
16fe0 6c 69 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70  lidated. .** Typ
16ff0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
17000 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
17010 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
17020 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
17030 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
17040 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
17050 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61  ><p>  The initia
17060 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
17070 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
17080 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a  column_text() .*
17090 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 73 71  *          or sq
170a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
170b0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
170c0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
170d0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
170e0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
170f0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
17100 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a  ring.</p></li>.*
17110 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68  *.** <li><p>  Th
17120 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
17130 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
17140 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
17150 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
17160 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69  **          sqli
17170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
17180 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
17190 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
171a0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
171b0 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46            to UTF
171c0 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a  -16.</p></li>.**
171d0 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
171e0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
171f0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
17200 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
17210 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
17220 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
17230 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
17240 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
17250 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
17260 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
17270 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
17280 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  /p></li>.** </ul
17290 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69  >.**.** Conversi
172a0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
172b0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
172c0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
172d0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
172e0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
172f0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
17300 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
17310 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
17320 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
17330 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
17340 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
17350 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
17360 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
17370 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
17380 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
17390 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
173a0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
173b0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69  , but sometime i
173c0 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73  t is.** not poss
173d0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
173e0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
173f0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
17400 69 64 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20  idated.  .**.** 
17410 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
17420 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
17430 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
17440 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
17450 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
17460 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
17470 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75   ways:.**.**  <u
17480 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
17490 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
174a0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
174b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
174c0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
174d0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
174e0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
174f0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
17500 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
17510 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
17520 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
17530 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
17540 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
17550 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75  6()</li>.**  </u
17560 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
17570 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
17580 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
17590 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
175a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
175b0 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c  lob(),.** or sql
175c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
175d0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
175e0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 20 69  rce the result i
175f0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a  nto the desired.
17600 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ** format, then 
17610 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
17620 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
17630 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
17640 62 79 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20  bytes16() to.** 
17650 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
17660 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
17670 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f   not mix call to
17680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
17690 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  text() or.** sql
176a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
176b0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
176c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
176d0 62 79 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20  bytes16().  And 
176e0 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61  do not.** mix ca
176f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
17700 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77  olumn_text16() w
17710 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
17720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
17730 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  s()..**.** The p
17740 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
17750 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
17760 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
17770 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
17780 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
17790 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
177a0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
177b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
177c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
177d0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
177e0 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72  lled.  The memor
177f0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
17800 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
17810 61 6e 64 20 62 6c 6f 62 73 20 69 73 20 66 72 65  and blobs is fre
17820 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
17830 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
17840 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
17850 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
17860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
17870 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
17880 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
17890 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b   etc. into .** [
178a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
178b0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f  .**.** If a memo
178c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
178d0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
178e0 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
178f0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
17900 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
17910 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
17920 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
17930 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
17940 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
17950 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
17960 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
17970 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
17980 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
17990 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
179a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
179b0 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
179c0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
179d0 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  OMEM]..*/.const 
179e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
179f0 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
17a00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
17a10 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
17a20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
17a30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
17a40 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
17a50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
17a60 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
17a70 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
17a80 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
17a90 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
17aa0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
17ab0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
17ac0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
17ad0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
17ae0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
17af0 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
17b00 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
17b10 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
17b20 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
17b30 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
17b40 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
17b50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
17b60 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
17b70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
17b80 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
17b90 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
17ba0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
17bb0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
17bc0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
17bd0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
17be0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
17bf0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
17c00 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
17c10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17c20 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
17c30 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
17c40 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ject.**.** The s
17c50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
17c60 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
17c70 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
17c80 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
17c90 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51  mt | compiled SQ
17ca0 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66  L statement]. If
17cb0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
17cc0 61 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73  as.** executed s
17cd0 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20  uccessfully, or 
17ce0 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20  not executed at 
17cf0 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  all, then SQLITE
17d00 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
17d10 0a 2a 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e  .** If execution
17d20 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
17d30 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e  t failed then an
17d40 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
17d50 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d  OR | error code]
17d60 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
17d70 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
17d80 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a  d error code].**
17d90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a   is returned. .*
17da0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
17db0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
17dc0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
17dd0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
17de0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  n of the.** [sql
17df0 69 74 65 33 5f 73 74 6d 74 20 7c 20 76 69 72 74  ite3_stmt | virt
17e00 75 61 6c 20 6d 61 63 68 69 6e 65 5d 2e 20 20 49  ual machine].  I
17e10 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  f the virtual ma
17e20 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a  chine has not .*
17e30 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
17e40 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
17e50 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
17e60 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
17e70 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
17e80 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69  an error or an i
17e90 6e 74 65 72 72 75 70 74 2e 20 20 28 53 65 65 20  nterrupt.  (See 
17ea0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
17eb0 70 74 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f  pt()].) .** Inco
17ec0 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d  mplete updates m
17ed0 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ay be rolled bac
17ee0 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f  k and transactio
17ef0 6e 73 20 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a  ns cancelled,  .
17f00 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ** depending on 
17f10 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  the circumstance
17f20 73 2c 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b  s, and the .** [
17f30 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
17f40 65 73 75 6c 74 20 63 6f 64 65 5d 20 72 65 74 75  esult code] retu
17f50 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51  rned will be [SQ
17f60 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a  LITE_ABORT]..*/.
17f70 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
17f80 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
17f90 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
17fa0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
17fb0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
17fc0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
17fd0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
17fe0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
17ff0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
18000 73 65 74 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74  set a .** [sqlit
18010 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c  e3_stmt | compil
18020 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
18030 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63  ] object..** bac
18040 6b 20 74 6f 20 69 74 27 73 20 69 6e 69 74 69 61  k to it's initia
18050 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
18060 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
18070 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61  ..** Any SQL sta
18080 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
18090 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
180a0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
180b0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
180c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
180d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
180e0 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
180f0 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
18100 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
18110 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
18120 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
18130 6e 67 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ngs..*/.int sqli
18140 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
18150 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
18160 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18170 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
18180 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
18190 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  s.**.** The foll
181a0 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
181b0 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
181c0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
181d0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a  s or aggregates.
181e0 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  ** or to redefin
181f0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
18200 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
18210 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
18220 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20  egates.  The.** 
18230 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20  difference only 
18240 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20  between the two 
18250 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  is that the seco
18260 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  nd parameter, th
18270 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65  e.** name of the
18280 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
18290 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
182a0 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55   is encoded in U
182b0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
182c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
182d0 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
182e0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
182f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
18300 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
18310 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
18320 65 20 5b 73 71 6c 69 74 65 33 20 7c 20 64 61 74  e [sqlite3 | dat
18330 61 62 61 73 65 20 68 61 6e 64 6c 65 5d 20 74 68  abase handle] th
18340 61 74 20 68 6f 6c 64 73 20 74 68 65 0a 2a 2a 20  at holds the.** 
18350 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
18360 61 67 67 72 65 67 61 74 65 20 69 73 20 74 6f 20  aggregate is to 
18370 62 65 20 61 64 64 65 64 20 6f 72 20 72 65 64 65  be added or rede
18380 66 69 6e 65 64 2e 20 49 66 20 61 20 73 69 6e 67  fined. If a sing
18390 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  le.** program us
183a0 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
183b0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
183c0 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65   internally, the
183d0 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  n SQL.** functio
183e0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
183f0 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69   must be added i
18400 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65  ndividually to e
18410 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ach database.** 
18420 68 61 6e 64 6c 65 20 77 69 74 68 20 77 68 69 63  handle with whic
18430 68 20 74 68 65 79 20 77 69 6c 6c 20 62 65 20 75  h they will be u
18440 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
18450 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18460 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
18470 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
18480 74 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a  to be created.**
18490 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a   or redefined..*
184a0 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * The length of 
184b0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
184c0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
184d0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
184e0 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d  he .** zero-term
184f0 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68  inator.  Note th
18500 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67  at the name leng
18510 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62  th limit is in b
18520 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61  ytes, not.** cha
18530 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74  racters.  Any at
18540 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
18550 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
18560 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
18570 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
18580 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  an SQLITE_ERROR 
18590 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
185a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
185b0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
185c0 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
185d0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
185e0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
185f0 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73  e takes. If this
18600 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
18610 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
18620 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
18630 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
18640 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
18650 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
18660 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
18670 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
18680 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
18690 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  what .** [SQLITE
186a0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
186b0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
186c0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
186d0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
186e0 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c  meters.  Any SQL
186f0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
18700 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
18710 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
18720 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46  ** work with UTF
18730 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
18740 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
18750 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
18760 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
18770 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
18780 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
18790 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49  than another.  I
187a0 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a  t is allowed to.
187b0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
187c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
187d0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
187e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
187f0 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
18800 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
18810 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
18820 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
18830 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
18840 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69  p..** When multi
18850 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
18860 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
18870 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
18880 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
18890 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
188a0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
188b0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
188c0 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
188d0 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
188e0 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
188f0 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
18900 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
18910 74 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74  t care what.** t
18920 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
18930 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
18940 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
18950 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c  hould be.** [SQL
18960 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
18970 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
18980 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
18990 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
189a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
189b0 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74  .** of the funct
189c0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
189d0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
189e0 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ter using.** [sq
189f0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
18a00 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  )]..**.** The se
18a10 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
18a20 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
18a30 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
18a40 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
18a50 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
18a60 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
18a70 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
18a80 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ent the SQL.** f
18a90 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
18aa0 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53  gate. A scalar S
18ab0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
18ac0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
18ad0 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  tation of.** the
18ae0 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20   xFunc callback 
18af0 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74  only, NULL point
18b00 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
18b10 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
18b20 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
18b30 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61  parameters. An a
18b40 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
18b50 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
18b60 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
18b70 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64  .** of xStep and
18b80 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
18b90 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
18ba0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20  d for xFunc. To 
18bb0 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69  delete an.** exi
18bc0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
18bd0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
18be0 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61   pass NULL for a
18bf0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
18c00 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  n.** callback..*
18c10 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69  *.** It is permi
18c20 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
18c30 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
18c40 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
18c50 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
18c60 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
18c70 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
18c80 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
18c90 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
18ca0 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
18cb0 72 69 6e 67 20 70 65 72 66 65 72 72 65 64 20 74  ring perferred t
18cc0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
18cd0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
18ce0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
18cf0 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65  ation most close
18d00 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
18d10 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
18d20 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
18d30 69 73 20 75 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20  is used..*/.int 
18d40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
18d50 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
18d60 65 33 20 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68  e3 *,.  const ch
18d70 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
18d80 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
18d90 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
18da0 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28   void*,.  void (
18db0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
18dc0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
18dd0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
18de0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
18df0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
18e00 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
18e10 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
18e20 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
18e30 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
18e40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
18e50 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
18e60 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 76  ite3*,.  const v
18e70 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
18e80 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
18e90 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
18ea0 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20    void*,.  void 
18eb0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
18ec0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
18ed0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
18ee0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
18ef0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
18f00 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
18f10 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
18f20 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
18f30 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
18f40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
18f50 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
18f60 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
18f70 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
18f80 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
18f90 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
18fa0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
18fb0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
18fc0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
18fd0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
18fe0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
18ff0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
19000 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
19010 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
19020 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
19030 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
19040 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
19050 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
19060 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
19070 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
19080 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
19090 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
190a0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
190b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
190c0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
190d0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
190e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
190f0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
19100 41 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74  API3REF: Obsolet
19110 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  e Functions.**.*
19120 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
19130 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62  s are all now ob
19140 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65  solete.  In orde
19150 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
19160 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
19170 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
19180 64 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e  der code, we con
19190 74 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74  tinue to support
191a0 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69  .** these functi
191b0 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ons.  However, n
191c0 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70  ew development p
191d0 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61  rojects should a
191e0 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
191f0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
19200 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
19210 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
19220 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
19230 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
19240 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
19250 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61  g to tell you wa
19260 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69  nt they do..*/.i
19270 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
19280 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
19290 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e  e3_context*);.in
192a0 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
192b0 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
192c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  ;.int sqlite3_tr
192d0 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
192e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
192f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69  qlite3_stmt*);.i
19300 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
19310 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
19320 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68  .void sqlite3_th
19330 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
19340 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
19350 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
19360 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
19370 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
19380 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
19390 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
193a0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
193b0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
193c0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
193d0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
193e0 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
193f0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
19400 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
19410 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
19420 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
19430 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
19440 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
19450 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
19460 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
19470 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
19480 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
19490 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
194a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
194b0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
194c0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
194d0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
194e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
194f0 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
19500 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  The 4th paramete
19510 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
19520 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
19530 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
19540 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
19550 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
19560 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
19570 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
19580 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
19590 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
195a0 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
195b0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
195c0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
195d0 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
195e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
195f0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
19600 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
19610 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
19620 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
19630 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  g .** [sqlite3_c
19640 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c  olumn_blob | sql
19650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f  ite3_column_* ro
19660 75 74 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74  utines] except t
19670 68 61 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f  hat .** these ro
19680 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
19690 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  ngle [sqlite3_va
196a0 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72 20 69 6e  lue*] pointer in
196b0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b  stead.** of an [
196c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
196d0 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
196e0 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
196f0 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ber..**.** The s
19700 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
19710 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
19720 65 78 74 72 61 63 74 73 20 61 20 55 54 46 31 36  extracts a UTF16
19730 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
19740 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
19750 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
19760 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a  machine.  The.**
19770 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
19780 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
19790 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
197a0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
197b0 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
197c0 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
197d0 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
197e0 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
197f0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  ctively..**.** T
19800 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
19810 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
19820 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
19830 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
19840 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
19850 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
19860 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
19870 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
19880 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
19890 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
198a0 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
198b0 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
198c0 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
198d0 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
198e0 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
198f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
19900 6f 72 64 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69  order.** words i
19910 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 6f  f the value is o
19920 72 69 67 69 6e 61 6c 20 61 20 73 74 72 69 6e 67  riginal a string
19930 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
19940 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
19950 65 6e 20 69 74 20 69 73 20 64 6f 6e 65 2e 20 20  en it is done.  
19960 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
19970 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20  version occurs. 
19980 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   The .** [SQLITE
19990 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
199a0 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
199b0 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
199c0 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  d..**.** Please 
199d0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
199e0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
199f0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
19a00 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  inter that.** is
19a10 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
19a20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
19a30 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
19a40 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
19a50 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
19a60 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
19a70 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
19a80 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
19a90 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
19aa0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
19ab0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
19ac0 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
19ad0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
19ae0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
19af0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
19b00 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20  t16()].  .**.** 
19b10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
19b20 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
19b30 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
19b40 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
19b50 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
19b60 75 70 70 6c 69 65 64 20 74 68 65 20 73 71 6c 69  upplied the sqli
19b70 74 65 33 5f 76 61 6c 75 65 2a 20 70 61 72 61 6d  te3_value* param
19b80 65 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c 20 69 66  eters..** Or, if
19b90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
19ba0 75 65 2a 20 61 72 67 75 6d 65 6e 74 20 63 6f 6d  ue* argument com
19bb0 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
19bc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
19bd0 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e()].** interfac
19be0 65 2c 20 74 68 65 6e 20 74 68 65 73 65 20 72 6f  e, then these ro
19bf0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
19c00 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
19c10 20 73 61 6d 65 20 74 68 72 65 61 64 0a 2a 2a 20   same thread.** 
19c20 74 68 61 74 20 72 61 6e 20 5b 73 71 6c 69 74 65  that ran [sqlite
19c30 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
19c40 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  ]..*/.const void
19c50 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
19c60 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
19c70 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
19c80 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
19c90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
19ca0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
19cb0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
19cc0 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65  _value*);.double
19cd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
19ce0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
19cf0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
19d00 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
19d10 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71  ite3_value*);.sq
19d20 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
19d30 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
19d40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
19d50 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
19d60 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
19d70 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
19d80 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
19d90 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
19da0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
19db0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
19dc0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
19dd0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
19de0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
19df0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
19e00 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
19e10 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
19e20 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
19e30 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
19e40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
19e50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
19e60 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
19e70 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
19e80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
19e90 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
19ea0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
19eb0 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65  *.** The impleme
19ec0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65  ntation of aggre
19ed0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
19ee0 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74  ns use this rout
19ef0 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a  ine to allocate.
19f00 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66  ** a structure f
19f10 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
19f20 20 73 74 61 74 65 2e 20 20 54 68 65 20 66 69 72   state.  The fir
19f30 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
19f40 74 69 6e 65 0a 2a 2a 20 69 73 20 63 61 6c 6c 65  tine.** is calle
19f50 64 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  d for a particul
19f60 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 61 20  ar aggregate, a 
19f70 6e 65 77 20 73 74 72 75 63 74 75 72 65 20 6f 66  new structure of
19f80 20 73 69 7a 65 20 6e 42 79 74 65 73 0a 2a 2a 20   size nBytes.** 
19f90 69 73 20 61 6c 6c 6f 63 61 74 65 64 2c 20 7a 65  is allocated, ze
19fa0 72 6f 65 64 2c 20 61 6e 64 20 72 65 74 75 72 6e  roed, and return
19fb0 65 64 2e 20 20 4f 6e 20 73 75 62 73 65 71 75 65  ed.  On subseque
19fc0 6e 74 20 63 61 6c 6c 73 20 28 66 6f 72 20 74 68  nt calls (for th
19fd0 65 0a 2a 2a 20 73 61 6d 65 20 61 67 67 72 65 67  e.** same aggreg
19fe0 61 74 65 20 69 6e 73 74 61 6e 63 65 29 20 74 68  ate instance) th
19ff0 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
1a000 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1a010 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
1a020 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  * of the aggrega
1a030 74 65 20 63 61 6e 20 75 73 65 20 74 68 65 20 72  te can use the r
1a040 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74  eturned buffer t
1a050 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74  o accumulate dat
1a060 61 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 66  a..**.** The buf
1a070 66 65 72 20 61 6c 6c 6f 63 61 74 65 64 20 69 73  fer allocated is
1a080 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
1a090 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 77  ally by SQLite w
1a0a0 68 61 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  han the aggregat
1a0b0 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c  e.** query concl
1a0c0 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
1a0d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1a0e0 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79  should be a copy
1a0f0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   of the .** [sql
1a100 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
1a110 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
1a120 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
1a130 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1a140 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1a150 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
1a160 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
1a170 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
1a180 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
1a190 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
1a1a0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
1a1b0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
1a1c0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
1a1d0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
1a1e0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
1a1f0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1a200 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
1a210 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
1a220 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
1a230 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a240 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
1a250 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
1a260 2a 20 54 68 65 20 70 55 73 65 72 44 61 74 61 20  * The pUserData 
1a270 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a280 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1a290 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
1a2a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
1a2b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
1a2c0 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73  ] routines.** us
1a2d0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 75  ed to register u
1a2e0 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 69 73  ser functions is
1a2f0 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a   available to.**
1a300 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1a310 69 6f 6e 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ion of the funct
1a320 69 6f 6e 20 75 73 69 6e 67 20 74 68 69 73 20 63  ion using this c
1a330 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  all..**.** This 
1a340 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
1a350 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
1a360 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
1a370 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
1a380 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
1a390 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
1a3a0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
1a3b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1a3c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a3d0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
1a3e0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
1a3f0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
1a400 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
1a410 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
1a420 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
1a430 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
1a440 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68  e meta-data with
1a450 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
1a460 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
1a470 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
1a480 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
1a490 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
1a4a0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
1a4b0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
1a4c0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
1a4d0 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
1a4e0 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
1a4f0 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d  ated meta-data m
1a500 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
1a510 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
1a520 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
1a530 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
1a540 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
1a550 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
1a560 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
1a570 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
1a580 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
1a590 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
1a5a0 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d  ored as.** meta-
1a5b0 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
1a5c0 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
1a5d0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
1a5e0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
1a5f0 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
1a600 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
1a610 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
1a620 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
1a630 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
1a640 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
1a650 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
1a660 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
1a670 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
1a680 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
1a690 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
1a6a0 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
1a6b0 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
1a6c0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
1a6d0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
1a6e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
1a6f0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
1a700 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  -data.** associa
1a710 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68  ted with the Nth
1a720 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 20   argument value 
1a730 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 53  to the current S
1a740 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  QL function.** c
1a750 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20 69 73 20  all, where N is 
1a760 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1a770 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d 65 74 61  eter. If no meta
1a780 2d 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 73  -data has been s
1a790 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 76  et for.** that v
1a7a0 61 6c 75 65 2c 20 74 68 65 6e 20 61 20 4e 55 4c  alue, then a NUL
1a7b0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
1a7c0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
1a7d0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
1a7e0 64 61 74 61 28 29 20 69 73 20 75 73 65 64 20 74  data() is used t
1a7f0 6f 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  o associate meta
1a800 2d 64 61 74 61 20 77 69 74 68 20 61 6e 20 53 51  -data with an SQ
1a810 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 72  L.** function ar
1a820 67 75 6d 65 6e 74 2e 20 54 68 65 20 74 68 69 72  gument. The thir
1a830 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
1a840 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1a850 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 74 6f 20  meta-data.** to 
1a860 62 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  be associated wi
1a870 74 68 20 74 68 65 20 4e 74 68 20 75 73 65 72 20  th the Nth user 
1a880 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
1a890 74 20 76 61 6c 75 65 2e 20 54 68 65 20 66 6f 75  t value. The fou
1a8a0 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rth.** parameter
1a8b0 20 73 70 65 63 69 66 69 65 73 20 61 20 64 65 73   specifies a des
1a8c0 74 72 75 63 74 6f 72 20 74 68 61 74 20 77 69 6c  tructor that wil
1a8d0 6c 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 20 74  l be called on t
1a8e0 68 65 20 6d 65 74 61 2d 0a 2a 2a 20 64 61 74 61  he meta-.** data
1a8f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 72 65 6c 65   pointer to rele
1a900 61 73 65 20 69 74 20 77 68 65 6e 20 69 74 20 69  ase it when it i
1a910 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
1a920 69 72 65 64 2e 20 49 66 20 74 68 65 20 0a 2a 2a  ired. If the .**
1a930 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 4e   destructor is N
1a940 55 4c 4c 2c 20 69 74 20 69 73 20 6e 6f 74 20 69  ULL, it is not i
1a950 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  nvoked..**.** In
1a960 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d   practice, meta-
1a970 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
1a980 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
1a990 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
1a9a0 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
1a9b0 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
1a9c0 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
1a9d0 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
1a9e0 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
1a9f0 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73  nd SQL variables
1aa00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1aa10 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
1aa20 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
1aa30 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
1aa40 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
1aa50 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
1aa60 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
1aa70 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
1aa80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1aa90 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
1aaa0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
1aab0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
1aac0 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20  t*, int, void*, 
1aad0 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
1aae0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
1aaf0 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
1ab00 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
1ab10 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
1ab20 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  or.**.** These a
1ab30 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
1ab40 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
1ab50 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
1ab60 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
1ab70 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
1ab80 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
1ab90 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
1aba0 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65  blob()].  If the
1abb0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
1abc0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
1abd0 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
1abe0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
1abf0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
1ac00 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
1ac10 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
1ac20 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
1ac30 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
1ac40 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51  yed.  The .** SQ
1ac50 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
1ac60 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
1ac70 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
1ac80 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
1ac90 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
1aca0 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
1acb0 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
1acc0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
1acd0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
1ace0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
1acf0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
1ad00 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
1ad10 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
1ad20 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
1ad30 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
1ad40 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
1ad50 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
1ad60 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
1ad70 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
1ad80 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
1ad90 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
1ada0 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
1adb0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
1adc0 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
1add0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
1ade0 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
1adf0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
1ae00 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
1ae10 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
1ae20 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
1ae30 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a  QL Function.**.*
1ae40 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1ae50 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
1ae60 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
1ae70 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
1ae80 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
1ae90 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
1aea0 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
1aeb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
1aec0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
1aed0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
1aee0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
1aef0 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
1af00 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
1af10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
1af20 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
1af30 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a  much like the .*
1af40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1af50 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
1af60 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66  ind_*] family of
1af70 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a   functions used.
1af80 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ** to bind value
1af90 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
1afa0 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
1afb0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1afc0 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  Refer to the.** 
1afd0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1afe0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
1aff0 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  d_* documentatio
1b000 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  n] for.** additi
1b010 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1b020 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1b030 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
1b040 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
1b050 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
1b060 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
1b070 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
1b080 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
1b090 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
1b0a0 70 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 70  ption.  The.** p
1b0b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1b0c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
1b0d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1b0e0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
1b0f0 2a 20 69 73 20 74 68 65 20 74 65 78 74 20 6f 66  * is the text of
1b100 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1b110 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
1b120 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
1b130 69 67 28 29 20 63 61 75 73 65 20 74 68 65 20 66  ig() cause the f
1b140 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
1b150 74 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 72  tation.** to thr
1b160 6f 77 20 61 6e 64 20 65 72 72 6f 72 20 69 6e 64  ow and error ind
1b170 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
1b180 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
1b190 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72   to long.** to r
1b1a0 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
1b1b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
1b1c0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
1b1d0 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  om within the sa
1b1e0 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
1b1f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
1b200 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1b210 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
1b220 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2e 0a  ntext] pointer..
1b230 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1b240 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
1b250 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
1b260 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
1b270 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1b280 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1b290 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
1b2a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
1b2b0 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
1b2c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
1b2d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1b2e0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
1b2f0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
1b300 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
1b310 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
1b320 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
1b330 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
1b340 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
1b350 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
1b360 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
1b370 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
1b380 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
1b390 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
1b3a0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1b3b0 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
1b3c0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
1b3d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1b3e0 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
1b3f0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
1b400 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
1b410 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
1b420 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
1b430 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
1b440 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
1b450 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b460 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
1b470 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
1b480 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1b490 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
1b4a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b4b0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1b4c0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
1b4d0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1b4e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
1b4f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1b500 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
1b510 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
1b520 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
1b530 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
1b540 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
1b550 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
1b560 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
1b570 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
1b580 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
1b590 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1b5a0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
1b5b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1b5c0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
1b5d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1b5e0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
1b5f0 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
1b600 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
1b610 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
1b620 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
1b630 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
1b640 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
1b650 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a  quences to the.*
1b660 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  * [sqlite3*] han
1b670 64 6c 65 20 73 70 65 63 69 66 69 65 64 20 61 73  dle specified as
1b680 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1b690 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent. .**.** The 
1b6a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
1b6b0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1b6c0 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
1b6d0 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
1b6e0 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
1b6f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1b700 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1b710 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1b720 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
1b730 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
1b740 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1b750 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 20  collation16().  
1b760 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
1b770 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
1b780 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1b790 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
1b7a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  nt..**.** The th
1b7b0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  ird argument mus
1b7c0 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
1b7d0 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
1b7e0 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
1b7f0 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20  ITE_UTF16LE] or 
1b800 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
1b810 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  , indicating tha
1b820 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c  t the user-suppl
1b830 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65  ied.** routine e
1b840 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73  xpects to be pas
1b850 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  sed pointers to 
1b860 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20  strings encoded 
1b870 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20  using UTF-8,.** 
1b880 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
1b890 64 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62  dian or UTF-16 b
1b8a0 69 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  ig-endian respec
1b8b0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20  tively..**.** A 
1b8c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
1b8d0 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
1b8e0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
1b8f0 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
1b900 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  .** argument. If
1b910 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69   it is NULL, thi
1b920 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  s is the same as
1b930 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
1b940 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
1b950 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c  nce (so that SQL
1b960 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20  ite cannot call 
1b970 69 74 20 61 6e 79 6d 6f 72 65 29 2e 20 45 61 63  it anymore). Eac
1b980 68 20 74 69 6d 65 20 74 68 65 20 75 73 65 72 0a  h time the user.
1b990 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63  ** supplied func
1b9a0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c  tion is invoked,
1b9b0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20   it is passed a 
1b9c0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1b9d0 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  * passed as.** t
1b9e0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
1b9f0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  nt to sqlite3_cr
1ba00 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
1ba10 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
1ba20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
1ba30 36 28 29 20 61 73 20 69 74 73 20 66 69 72 73 74  6() as its first
1ba40 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1ba50 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1ba60 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
1ba70 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20 72   user-supplied r
1ba80 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73  outine are two s
1ba90 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20  trings,.** each 
1baa0 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
1bab0 20 5b 6c 65 6e 67 74 68 2c 20 64 61 74 61 5d 20   [length, data] 
1bac0 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64  pair and encoded
1bad0 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
1bae0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73  .** that was pas
1baf0 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
1bb00 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74   argument when t
1bb10 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
1bb20 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67  uence was.** reg
1bb30 69 73 74 65 72 65 64 2e 20 54 68 65 20 75 73 65  istered. The use
1bb40 72 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  r routine should
1bb50 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65   return negative
1bb60 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69  , zero or positi
1bb70 76 65 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72  ve if.** the fir
1bb80 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
1bb90 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
1bba0 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
1bbb0 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  n the second.** 
1bbc0 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54  string. i.e. (ST
1bbd0 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29  RING1 - STRING2)
1bbe0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1bbf0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1bc00 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
1bc10 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
1bc20 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
1bc30 2a 2a 20 65 78 63 61 70 74 20 74 68 61 74 20 69  ** excapt that i
1bc40 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61  t takes an extra
1bc50 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
1bc60 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
1bc70 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  for.** the colla
1bc80 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72  tion.  The destr
1bc90 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20  uctor is called 
1bca0 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
1bcb0 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79  on is.** destroy
1bcc0 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64  ed and is passed
1bcd0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
1bce0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1bcf0 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a  void* pointer.**
1bd00 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1bd10 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1bd20 5f 76 32 28 29 2e 20 20 43 6f 6c 6c 61 74 69 6f  _v2().  Collatio
1bd30 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  ns are destroyed
1bd40 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72   when.** they ar
1bd50 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
1bd60 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
1bd70 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
1bd80 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a  ation functions.
1bd90 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ** or when the [
1bda0 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61  sqlite3*] databa
1bdb0 73 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f  se handle is clo
1bdc0 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
1bdd0 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
1bde0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
1bdf0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
1be00 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  v2() interface i
1be10 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
1be20 6e 64 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  nd.** subject to
1be30 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
1be40 65 20 72 65 6c 65 61 73 65 73 2e 20 20 54 68 65  e releases.  The
1be50 20 6f 74 68 65 72 20 63 6f 6c 6c 61 74 69 6f 6e   other collation
1be60 20 63 72 65 61 74 69 6f 6e 0a 2a 2a 20 66 75 6e   creation.** fun
1be70 63 74 69 6f 6e 73 20 61 72 65 20 73 74 61 62 6c  ctions are stabl
1be80 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1be90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1bea0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
1beb0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1bec0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
1bed0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
1bee0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
1bef0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
1bf00 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
1bf10 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
1bf20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1bf30 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
1bf40 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
1bf50 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
1bf60 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
1bf70 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
1bf80 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
1bf90 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
1bfa0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
1bfb0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
1bfc0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
1bfd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
1bfe0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
1bff0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
1c000 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
1c010 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
1c020 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
1c030 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
1c040 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
1c050 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
1c060 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
1c070 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
1c080 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
1c090 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  ks.**.** To avoi
1c0a0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
1c0b0 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
1c0c0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
1c0d0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
1c0e0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
1c0f0 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
1c100 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
1c110 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
1c120 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1c130 20 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61   handle to be ca
1c140 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  lled whenever an
1c150 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
1c160 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
1c170 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  .** required..**
1c180 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74  .** If the funct
1c190 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
1c1a0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
1c1b0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
1c1c0 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
1c1d0 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
1c1e0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
1c1f0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
1c200 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
1c210 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
1c220 64 20 69 6e 20 55 54 46 2d 38 2e 20 49 66 20 73  d in UTF-8. If s
1c230 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
1c240 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
1c250 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a  sed, the names.*
1c260 2a 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  * are passed as 
1c270 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
1c280 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1c290 64 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65  der. A call to e
1c2a0 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ither.** functio
1c2b0 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65  n replaces any e
1c2c0 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b  xisting callback
1c2d0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1c2e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1c2f0 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
1c300 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
1c310 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
1c320 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
1c330 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
1c340 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
1c350 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
1c360 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
1c370 31 36 28 29 2e 20 54 68 65 20 73 65 63 6f 6e 64  16(). The second
1c380 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1c390 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e   database.** han
1c3a0 64 6c 65 2e 20 54 68 65 20 74 68 69 72 64 20 61  dle. The third a
1c3b0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
1c3c0 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
1c3d0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
1c3e0 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ], or.** [SQLITE
1c3f0 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
1c400 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
1c410 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
1c420 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
1c430 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
1c440 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 54 68  ion required. Th
1c450 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1c460 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
1c470 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
1c480 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
1c490 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ence..**.** The 
1c4a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c4b0 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
1c4c0 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
1c4d0 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
1c4e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1c4f0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
1c500 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1c510 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
1c520 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
1c530 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
1c540 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2()]..*/.int sql
1c550 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
1c560 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33  eeded(.  sqlite3
1c570 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20  *, .  void*, .  
1c580 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
1c590 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
1c5a0 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  Rep,const char*)
1c5b0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1c5c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
1c5d0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
1c5e0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
1c5f0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
1c600 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
1c610 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
1c620 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
1c630 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
1c640 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
1c650 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
1c660 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
1c670 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
1c680 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
1c690 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
1c6a0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
1c6b0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
1c6c0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
1c6d0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
1c6e0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
1c6f0 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
1c700 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1c710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
1c720 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
1c730 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
1c740 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
1c750 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
1c760 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
1c770 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
1c780 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
1c790 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
1c7a0 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
1c7b0 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
1c7c0 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
1c7d0 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
1c7e0 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
1c7f0 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
1c800 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
1c810 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
1c820 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
1c830 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
1c840 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
1c850 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
1c860 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
1c870 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
1c880 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
1c890 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1c8a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1c8b0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
1c8c0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
1c8d0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
1c8e0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
1c8f0 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
1c900 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c910 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
1c920 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
1c930 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ime.**.** This f
1c940 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
1c950 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
1c960 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
1c970 63 75 74 69 6f 6e 0a 2a 2a 20 61 20 6e 75 6d 62  cution.** a numb
1c980 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
1c990 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
1c9a0 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
1c9b0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
1c9c0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
1c9d0 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
1c9e0 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
1c9f0 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  h .** millisecon
1ca00 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
1ca10 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
1ca20 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
1ca30 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e   up to .** the n
1ca40 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
1ca50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
1ca60 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1ca70 65 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20  ep actually .** 
1ca80 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
1ca90 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1caa0 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
1cab0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
1cac0 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
1cad0 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
1cae0 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
1caf0 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
1cb00 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1cb10 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
1cb20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
1cb30 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
1cb40 20 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65   CAPI3REF:  Name
1cb50 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
1cb60 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
1cb70 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 49 66 20   Files.**.** If 
1cb80 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
1cb90 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
1cba0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
1cbb0 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
1cbc0 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
1cbd0 65 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74  er (a.ka. direct
1cbe0 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
1cbf0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
1cc00 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
1cc10 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  ite will be plac
1cc20 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
1cc30 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76  tory.  If this v
1cc40 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55  ariable.** is NU
1cc50 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
1cc60 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73   SQLite does a s
1cc70 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
1cc80 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61  ropriate tempora
1cc90 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63  ry.** file direc
1cca0 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
1ccb0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f  s not safe to mo
1ccc0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
1ccd0 6c 65 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61  le once a databa
1cce0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1ccf0 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64   has been opened
1cd00 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  .  It is intende
1cd10 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
1cd20 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
1cd30 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
1cd40 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
1cd50 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
1cd60 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
1cd70 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
1cd80 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
1cd90 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68   and remain unch
1cda0 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72  anged thereafter
1cdb0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1cdc0 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
1cdd0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
1cde0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cdf0 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  :  Test To See I
1ce00 66 20 54 68 65 20 44 61 74 61 62 61 73 65 20 49  f The Database I
1ce10 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74  s In Auto-Commit
1ce20 20 4d 6f 64 65 0a 2a 2a 0a 2a 2a 20 54 65 73 74   Mode.**.** Test
1ce30 20 74 6f 20 73 65 65 20 77 68 65 74 68 65 72 20   to see whether 
1ce40 6f 72 20 6e 6f 74 20 74 68 65 20 64 61 74 61 62  or not the datab
1ce50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1ce60 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a  s in autocommit.
1ce70 2a 2a 20 6d 6f 64 65 2e 20 20 52 65 74 75 72 6e  ** mode.  Return
1ce80 20 54 52 55 45 20 69 66 20 69 74 20 69 73 20 61   TRUE if it is a
1ce90 6e 64 20 46 41 4c 53 45 20 69 66 20 6e 6f 74 2e  nd FALSE if not.
1cea0 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64    Autocommit mod
1ceb0 65 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65  e is on.** by de
1cec0 66 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d  fault.  Autocomm
1ced0 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  it is disabled b
1cee0 79 20 61 20 42 45 47 49 4e 20 73 74 61 74 65 6d  y a BEGIN statem
1cef0 65 6e 74 20 61 6e 64 20 72 65 65 6e 61 62 6c 65  ent and reenable
1cf00 64 0a 2a 2a 20 62 79 20 74 68 65 20 6e 65 78 74  d.** by the next
1cf10 20 43 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c 42   COMMIT or ROLLB
1cf20 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ACK..**.** If an
1cf30 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
1cf40 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
1cf50 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
1cf60 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
1cf70 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
1cf80 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
1cf90 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
1cfa0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
1cfb0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
1cfc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
1cfd0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
1cfe0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1cff0 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54  API3REF:  Find T
1d000 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
1d010 6c 65 20 41 73 73 6f 63 69 61 74 65 64 20 57 69  le Associated Wi
1d020 74 68 20 41 20 50 72 65 70 61 72 65 64 20 53 74  th A Prepared St
1d030 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52 65  atement.**.** Re
1d040 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
1d050 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e  3*] database han
1d060 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a  dle to which a.*
1d070 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
1d080 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
1d090 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a  ment] belongs..*
1d0a0 2a 20 54 68 69 73 20 69 73 20 74 68 65 20 73 61  * This is the sa
1d0b0 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  me database hand
1d0c0 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74  le that was.** t
1d0d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1d0e0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
1d0f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d100 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a  or its variants.
1d110 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65 64  ** that was used
1d120 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 73   to create the s
1d130 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1d140 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a  first place..*/.
1d150 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
1d160 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
1d170 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a  e3_stmt*);.../*.
1d180 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1d190 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
1d1a0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
1d1b0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68  llbacks.**.** Th
1d1c0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
1d1d0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
1d1e0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 62  k functions to b
1d1f0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
1d200 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
1d210 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  .** is committed
1d220 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e   or rolled back.
1d230 20 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d    The pArg argum
1d240 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
1d250 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20  rough.** to the 
1d260 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68  callback.  If th
1d270 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
1d280 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
1d290 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73  tion .** returns
1d2a0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1d2b0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
1d2c0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
1d2d0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ollback..**.** I
1d2e0 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
1d2f0 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
1d300 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
1d310 73 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20  s pArg value is 
1d320 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68  returned..** Oth
1d330 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72  erwise NULL is r
1d340 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  eturned..**.** R
1d350 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
1d360 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
1d370 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
1d380 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ..**.** For the 
1d390 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
1d3a0 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74   API, a transact
1d3b0 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68  ion is said to h
1d3c0 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c  ave been .** rol
1d3d0 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
1d3e0 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
1d3f0 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
1d400 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
1d410 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
1d420 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
1d430 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
1d440 63 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54 68 65  ck to occur. The
1d450 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73   .** callback is
1d460 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
1d470 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
1d480 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
1d490 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62 65  olled.** back be
1d4a0 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
1d4b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1d4c0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
1d4d0 68 65 73 65 20 61 72 65 20 65 78 70 65 72 69 6d  hese are experim
1d4e0 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
1d4f0 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74   and are subject
1d500 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76   to change..*/.v
1d510 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
1d520 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
1d530 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
1d540 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
1d550 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
1d560 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
1d570 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
1d580 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1d590 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
1d5a0 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
1d5b0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
1d5c0 2a 2a 20 52 65 67 69 73 74 65 72 20 61 20 63 61  ** Register a ca
1d5d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1d5e0 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
1d5f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65  e connection ide
1d600 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ntified by the .
1d610 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  ** first argumen
1d620 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  t to be invoked 
1d630 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
1d640 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
1d650 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
1d660 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
1d670 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
1d680 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
1d690 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  unction for the 
1d6a0 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73  same .** databas
1d6b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1d6c0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
1d6d0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
1d6e0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
1d6f0 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
1d700 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
1d710 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75  n a .** row is u
1d720 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
1d730 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 68 65   or deleted. The
1d740 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1d750 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1d760 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20  is.** a copy of 
1d770 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1d780 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70  nt to sqlite3_up
1d790 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68 65  date_hook(). The
1d7a0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b   second callback
1d7b0 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73   .** argument is
1d7c0 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f 49   one of SQLITE_I
1d7d0 4e 53 45 52 54 2c 20 53 51 4c 49 54 45 5f 44 45  NSERT, SQLITE_DE
1d7e0 4c 45 54 45 20 6f 72 20 53 51 4c 49 54 45 5f 55  LETE or SQLITE_U
1d7f0 50 44 41 54 45 2c 20 64 65 70 65 6e 64 69 6e 67  PDATE, depending
1d800 0a 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  .** on the opera
1d810 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
1d820 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f   the callback to
1d830 20 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68 65   be invoked. The
1d840 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66   third and .** f
1d850 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
1d860 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1d870 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
1d880 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
1d890 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e   and .** table n
1d8a0 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
1d8b0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
1d8c0 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62   The final callb
1d8d0 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
1d8e0 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f   .** the rowid o
1d8f0 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68  f the row. In th
1d900 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64  e case of an upd
1d910 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65  ate, this is the
1d920 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a   rowid after .**
1d930 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
1d940 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  s place..**.** T
1d950 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
1d960 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
1d970 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
1d980 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a  em tables are.**
1d990 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20   modified (i.e. 
1d9a0 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
1d9b0 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
1d9c0 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  e)..**.** If ano
1d9d0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
1d9e0 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
1d9f0 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72  istered, its pAr
1da00 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  g value is retur
1da10 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  ned..** Otherwis
1da20 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
1da30 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ed..*/.void *sql
1da40 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
1da50 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
1da60 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
1da70 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
1da80 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
1da90 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
1daa0 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
1dab0 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62   CAPI3REF:  Enab
1dac0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68  le Or Disable Sh
1dad0 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65  ared Pager Cache
1dae0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1daf0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
1db00 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
1db10 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
1db20 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
1db30 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
1db40 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
1db50 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74  connections to t
1db60 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1db70 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20  ..** Sharing is 
1db80 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
1db90 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20  rgument is true 
1dba0 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20  and disabled if 
1dbb0 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  the argument.** 
1dbc0 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20  is false..**.** 
1dbd0 42 65 67 69 6e 6e 69 6e 67 20 69 6e 20 53 51 4c  Beginning in SQL
1dbe0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1dbf0 30 2c 20 63 61 63 68 65 20 73 68 61 72 69 6e 67  0, cache sharing
1dc00 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
1dc10 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20  disabled.** for 
1dc20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
1dc30 73 2e 20 20 49 6e 20 70 72 69 6f 72 20 76 65 72  s.  In prior ver
1dc40 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
1dc50 20 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20   sharing was.** 
1dc60 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
1dc70 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
1dc80 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
1dc90 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20  **.** The cache 
1dca0 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
1dcb0 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
1dcc0 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
1dcd0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
1dce0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
1dcf0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1dd00 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
1dd10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1dd20 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
1dd30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1dd40 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
1dd50 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
1dd60 6f 64 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  ode that was.** 
1dd70 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
1dd80 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
1dd90 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69  opened..**.** Vi
1dda0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e  rtual tables can
1ddb0 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68  not be used with
1ddc0 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e   a shared cache.
1ddd0 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a    When shared.**
1dde0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
1ddf0 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d, the [sqlite3_
1de00 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
1de10 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67   API used to reg
1de20 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c  ister.** virtual
1de30 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77   tables will alw
1de40 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72  ays return an er
1de50 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ror..**.** This 
1de60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1de70 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
1de80 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a  hared cache was.
1de90 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  ** enabled or di
1dea0 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75  sabled successfu
1deb0 6c 6c 79 2e 20 20 41 6e 20 5b 53 51 4c 49 54 45  lly.  An [SQLITE
1dec0 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63  _ERROR | error c
1ded0 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ode].** is retur
1dee0 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ned otherwise..*
1def0 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68  *.** Shared cach
1df00 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
1df10 20 64 65 66 61 75 6c 74 2e 20 20 42 75 74 20 74   default.  But t
1df20 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65  his might change
1df30 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65   in.** future re
1df40 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
1df50 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
1df60 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20  that care about 
1df70 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
1df80 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73  setting should s
1df90 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79  et it explicitly
1dfa0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1dfb0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
1dfc0 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
1dfd0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41 74 74  * CAPI3REF:  Att
1dfe0 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
1dff0 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 41  p Memory.**.** A
1e000 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 4e  ttempt to free N
1e010 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d   bytes of heap m
1e020 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
1e030 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
1e040 69 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ial.** memory al
1e050 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62  locations held b
1e060 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
1e070 69 62 72 61 72 79 20 28 65 78 61 6d 70 6c 65 3a  ibrary (example:
1e080 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 75 73 65 64   memory .** used
1e090 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
1e0a0 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72  se pages to impr
1e0b0 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 29  ove performance)
1e0c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1e0d0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
1e0e0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
1e0f0 49 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41  I3REF:  Impose A
1e100 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53   Limit On Heap S
1e110 69 7a 65 0a 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20  ize.**.** Place 
1e120 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f  a "soft" limit o
1e130 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
1e140 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
1e150 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
1e160 64 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20  d.** by SQLite. 
1e170 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20   If an internal 
1e180 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65  allocation is re
1e190 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74  quested .** that
1e1a0 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
1e1b0 65 20 73 70 65 63 69 66 69 65 64 20 6c 69 6d 69  e specified limi
1e1c0 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  t, [sqlite3_rele
1e1d0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73  ase_memory()] is
1e1e0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20  .** invoked one 
1e1f0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
1e200 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70   free up some sp
1e210 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61  ace before the a
1e220 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
1e230 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  made..**.** The 
1e240 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20  limit is called 
1e250 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20  "soft", because 
1e260 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  if [sqlite3_rele
1e270 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61  ase_memory()] ca
1e280 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66  nnot.** free suf
1e290 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
1e2a0 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
1e2b0 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
1e2c0 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
1e2d0 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
1e2e0 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
1e2f0 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
1e300 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
1e310 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  *.** A negative 
1e320 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
1e330 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74  r N means that t
1e340 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20  here is no soft 
1e350 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a  heap limit and.*
1e360 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
1e370 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
1e380 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  l only be called
1e390 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
1e3a0 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68  exhausted..** Th
1e3b0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
1e3c0 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
1e3d0 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
1e3e0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  .**.** SQLite ma
1e3f0 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72  kes a best effor
1e400 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73  t to honor the s
1e410 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20  oft heap limit. 
1e420 20 42 75 74 20 69 66 20 69 74 0a 2a 2a 20 69 73   But if it.** is
1e430 20 75 6e 61 62 6c 65 20 74 6f 20 72 65 64 75 63   unable to reduc
1e440 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62  e memory usage b
1e450 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 6c 69  elow the soft li
1e460 6d 69 74 2c 20 65 78 65 63 75 74 69 6f 6e 20 77  mit, execution w
1e470 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20  ill.** continue 
1e480 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72  without error or
1e490 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20   notification.  
1e4a0 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20  This is why the 
1e4b0 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c  limit is .** cal
1e4c0 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d  led a "soft" lim
1e4d0 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73  it.  It is advis
1e4e0 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ory only..**.** 
1e4f0 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
1e500 6d 69 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  mit is implement
1e510 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ed using the [sq
1e520 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
1e530 72 6d 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  rm()].** interfa
1e540 63 65 2e 20 20 4f 6e 6c 79 20 61 20 73 69 6e 67  ce.  Only a sing
1e550 6c 65 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20  le memory alarm 
1e560 69 73 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  is available in 
1e570 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 69  the default.** i
1e580 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1e590 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
1e5a0 69 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  if the applicati
1e5b0 6f 6e 20 61 6c 73 6f 20 75 73 65 73 20 74 68 65  on also uses the
1e5c0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d  .** memory alarm
1e5d0 20 69 6e 74 65 72 66 61 63 65 20 69 74 20 77 69   interface it wi
1e5e0 6c 6c 20 69 6e 74 65 72 66 65 72 65 20 77 69 74  ll interfere wit
1e5f0 68 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  h the operation 
1e600 6f 66 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68  of the.** soft h
1e610 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 75 6e  eap limit and un
1e620 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1e630 20 77 69 6c 6c 20 72 65 73 75 6c 74 2e 20 20 0a   will result.  .
1e640 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1e650 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1e660 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  5.0, this routin
1e670 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e  e only constrain
1e680 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ed the memory.**
1e690 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20   allocated by a 
1e6a0 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20  single thread - 
1e6b0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
1e6c0 69 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f  in which this ro
1e6d0 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20  utine.** runs.  
1e6e0 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53  Beginning with S
1e6f0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1e700 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65  5.0, the soft he
1e710 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61  ap limit is.** a
1e720 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68  pplied to all th
1e730 72 65 61 64 73 2e 20 20 54 68 65 20 76 61 6c 75  reads.  The valu
1e740 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 20  e specified for 
1e750 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
1e760 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70  mit.** is an upp
1e770 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20  er bound on the 
1e780 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  total memory all
1e790 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20  ocation for all 
1e7a0 74 68 72 65 61 64 73 2e 20 20 49 6e 0a 2a 2a 20  threads.  In.** 
1e7b0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68  version 3.5.0 th
1e7c0 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e  ere is no mechan
1e7d0 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67  ism for limiting
1e7e0 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20   the heap usage 
1e7f0 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61  for.** individua
1e800 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f  l threads..*/.vo
1e810 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  id sqlite3_soft_
1e820 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b  heap_limit(int);
1e830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e840 3a 20 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  :  Extract Metad
1e850 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
1e860 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a  mn Of A Table.**
1e870 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1e880 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61  .** returns meta
1e890 2d 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70  -data about a sp
1e8a0 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66  ecific column of
1e8b0 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61   a specific data
1e8c0 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63  base.** table ac
1e8d0 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74  cessible using t
1e8e0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  he connection ha
1e8f0 6e 64 6c 65 20 70 61 73 73 65 64 20 61 73 20 74  ndle passed as t
1e900 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
1e910 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a  n .** argument..
1e920 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e  **.** The column
1e930 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
1e940 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68  y the second, th
1e950 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
1e960 61 72 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a  arameters to .**
1e970 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
1e980 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1e990 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74  eter is either t
1e9a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1e9b0 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e  atabase.** (i.e.
1e9c0 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20   "main", "temp" 
1e9d0 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64  or an attached d
1e9e0 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e  atabase) contain
1e9f0 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
1ea00 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55  d.** table or NU
1ea10 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c  LL. If it is NUL
1ea20 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
1ea30 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
1ea40 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
1ea50 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
1ea60 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
1ea70 72 69 74 68 6d 20 61 73 20 74 68 65 20 64 61 74  rithm as the dat
1ea80 61 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65  abase engine use
1ea90 73 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65  s to .** resolve
1eaa0 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62   unqualified tab
1eab0 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a  le references..*
1eac0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
1ead0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
1eae0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
1eaf0 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
1eb00 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a  ble and column .
1eb10 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ** name of the d
1eb20 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72  esired column, r
1eb30 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69  espectively. Nei
1eb40 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61  ther of these pa
1eb50 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79  rameters .** may
1eb60 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
1eb70 4d 65 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  Meta information
1eb80 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
1eb90 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
1eba0 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
1ebb0 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
1ebc0 20 35 74 68 20 61 6e 64 20 73 75 62 73 65 71 75   5th and subsequ
1ebd0 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
1ebe0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
1ebf0 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a   Any of these .*
1ec00 2a 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20  * arguments may 
1ec10 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  be NULL, in whic
1ec20 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
1ec30 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
1ec40 20 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66   of meta .** inf
1ec50 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69  ormation is ommi
1ec60 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  tted..**.** <pre
1ec70 3e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20  >.** Parameter  
1ec80 20 20 20 4f 75 74 70 75 74 20 54 79 70 65 20 20     Output Type  
1ec90 20 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a      Description.
1eca0 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ** -------------
1ecb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ecc0 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35  ------.**.**   5
1ecd0 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  th         const
1ece0 20 63 68 61 72 2a 20 20 20 20 20 20 44 61 74 61   char*      Data
1ecf0 20 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20   type.**   6th  
1ed00 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61         const cha
1ed10 72 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20  r*      Name of 
1ed20 74 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c  the default coll
1ed30 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a  ation sequence .
1ed40 2a 2a 20 20 20 37 74 68 20 20 20 20 20 20 20 20  **   7th        
1ed50 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20   int            
1ed60 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f    True if the co
1ed70 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e  lumn has a NOT N
1ed80 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  ULL constraint.*
1ed90 2a 20 20 20 38 74 68 20 20 20 20 20 20 20 20 20  *   8th         
1eda0 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20  int             
1edb0 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c   True if the col
1edc0 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74  umn is part of t
1edd0 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a  he PRIMARY KEY.*
1ede0 2a 20 20 20 39 74 68 20 20 20 20 20 20 20 20 20  *   9th         
1edf0 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20  int             
1ee00 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c   True if the col
1ee10 75 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45  umn is AUTOINCRE
1ee20 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a  MENT.** </pre>.*
1ee30 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f  *.**.** The memo
1ee40 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ry pointed to by
1ee50 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70   the character p
1ee60 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
1ee70 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63   for the .** dec
1ee80 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e  laration type an
1ee90 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
1eea0 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e  ence is valid on
1eeb0 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  ly until the nex
1eec0 74 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  t .** call to an
1eed0 79 20 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e  y sqlite API fun
1eee0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
1eef0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61  the specified ta
1ef00 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20  ble is actually 
1ef10 61 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20  a view, then an 
1ef20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1ef30 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
1ef40 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e  specified column
1ef50 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69   is "rowid", "oi
1ef60 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20  d" or "_rowid_" 
1ef70 61 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47  and an .** INTEG
1ef80 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63  ER PRIMARY KEY c
1ef90 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
1efa0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
1efb0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
1efc0 70 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  put .** paramete
1efd0 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74  rs are set for t
1efe0 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  he explicitly de
1eff0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49  clared column. I
1f000 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a  f there is no.**
1f010 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
1f020 61 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c  ared IPK column,
1f030 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
1f040 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1f050 73 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f  set as .** follo
1f060 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  ws:.**.** <pre>.
1f070 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65  **     data type
1f080 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20  : "INTEGER".**  
1f090 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71     collation seq
1f0a0 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a  uence: "BINARY".
1f0b0 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a  **     not null:
1f0c0 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72   0.**     primar
1f0d0 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20  y key: 1.**     
1f0e0 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20  auto increment: 
1f0f0 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a  0.** </pre>.**.*
1f100 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
1f110 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20  may load one or 
1f120 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f  more schemas fro
1f130 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  m database files
1f140 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  . If an.** error
1f150 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
1f160 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  his process, or 
1f170 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  if the requested
1f180 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
1f190 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  .** cannot be fo
1f1a0 75 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65  und, an SQLITE e
1f1b0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
1f1c0 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72  urned and an err
1f1d0 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65  or message.** le
1f1e0 66 74 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  ft in the databa
1f1f0 73 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65  se handle (to be
1f200 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67   retrieved using
1f210 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
1f220 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  ))..**.** This A
1f230 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  PI is only avail
1f240 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
1f250 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
1f260 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
1f270 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
1f280 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72  N_METADATA prepr
1f290 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
1f2a0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
1f2b0 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c  qlite3_table_col
1f2c0 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20  umn_metadata(.  
1f2d0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1f2e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
1f2f0 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
1f300 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1f310 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
1f320 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61    /* Database na
1f330 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20  me or NULL */.  
1f340 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62  const char *zTab
1f350 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54  leName,     /* T
1f360 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  able name */.  c
1f370 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
1f380 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f  mnName,    /* Co
1f390 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  lumn name */.  c
1f3a0 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61  har const **pzDa
1f3b0 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55  taType,    /* OU
1f3c0 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64  TPUT: Declared d
1f3d0 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68  ata type */.  ch
1f3e0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c  ar const **pzCol
1f3f0 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54  lSeq,     /* OUT
1f400 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73  PUT: Collation s
1f410 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a  equence name */.
1f420 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c    int *pNotNull,
1f430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1f440 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
1f450 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
1f460 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20  aint exists */. 
1f470 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65   int *pPrimaryKe
1f480 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  y,           /* 
1f490 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
1f4a0 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50  column part of P
1f4b0 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74  K */.  int *pAut
1f4c0 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20  oinc            
1f4d0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
1f4e0 75 65 20 69 66 20 63 6f 6c 75 6d 73 20 69 73 20  ue if colums is 
1f4f0 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a  auto-increment *
1f500 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1f510 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78  3REF: Load An Ex
1f520 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74  tension.**.** At
1f530 74 65 6d 70 74 20 74 6f 20 6c 6f 61 64 20 61 6e  tempt to load an
1f540 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
1f550 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  n library contai
1f560 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a  ned in the file.
1f570 2a 2a 20 7a 46 69 6c 65 2e 20 20 54 68 65 20 65  ** zFile.  The e
1f580 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
1f590 72 6f 63 2e 20 20 7a 50 72 6f 63 20 6d 61 79 20  roc.  zProc may 
1f5a0 62 65 20 30 20 69 6e 20 77 68 69 63 68 20 63 61  be 0 in which ca
1f5b0 73 65 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f  se the.** name o
1f5c0 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
1f5d0 74 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73  t defaults to "s
1f5e0 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e  qlite3_extension
1f5f0 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65  _init"..**.** Re
1f600 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1f610 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
1f620 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
1f630 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73  f something goes
1f640 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66   wrong..**.** If
1f650 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1f660 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73   and pzErrMsg is
1f670 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 66 69 6c   not 0, then fil
1f680 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68  l *pzErrMsg with
1f690 20 0a 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73 61   .** error messa
1f6a0 67 65 20 74 65 78 74 2e 20 20 54 68 65 20 63 61  ge text.  The ca
1f6b0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73  lling function s
1f6c0 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20  hould free this 
1f6d0 6d 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c  memory.** by cal
1f6e0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
1f6f0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74  ee()]..**.** Ext
1f700 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d  ension loading m
1f710 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75  ust be enabled u
1f720 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
1f730 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
1f740 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20  ion()].** prior 
1f750 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  to calling this 
1f760 41 50 49 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  API or an error 
1f770 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
1f780 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1f790 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
1f7a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1f7b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64           /* Load
1f7c0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
1f7d0 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73  nto this databas
1f7e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a  e connection */.
1f7f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
1f800 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ile,    /* Name 
1f810 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69  of the shared li
1f820 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  brary containing
1f830 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20   extension */.  
1f840 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f  const char *zPro
1f850 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70  c,    /* Entry p
1f860 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66  oint.  Derived f
1f870 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a  rom zFile if 0 *
1f880 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1f890 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74  Msg       /* Put
1f8a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68   error message h
1f8b0 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a  ere if not 0 */.
1f8c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f8d0 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44  EF:  Enable Or D
1f8e0 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e  isable Extension
1f8f0 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53   Loading.**.** S
1f900 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e  o as not to open
1f910 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20   security holes 
1f920 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61  in older applica
1f930 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a  tions that are.*
1f940 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20  * unprepared to 
1f950 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73  deal with extens
1f960 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64  ion loading, and
1f970 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64   as a means of d
1f980 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65  isabling.** exte
1f990 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68  nsion loading wh
1f9a0 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75  ile evaluating u
1f9b0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c  ser-entered SQL,
1f9c0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a   the following.*
1f9d0 2a 20 41 50 49 20 69 73 20 70 72 6f 76 69 64 65  * API is provide
1f9e0 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73  d to turn the [s
1f9f0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
1fa00 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69  nsion()] mechani
1fa10 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66  sm on and.** off
1fa20 2e 20 20 49 74 20 69 73 20 6f 66 66 20 62 79 20  .  It is off by 
1fa30 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 74 69  default.  See ti
1fa40 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a  cket #1863..**.*
1fa50 2a 20 43 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  * Call this rout
1fa60 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d  ine with onoff==
1fa70 31 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73  1 to turn extens
1fa80 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a  ion loading on.*
1fa90 2a 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69  * and call it wi
1faa0 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74  th onoff==0 to t
1fab0 75 72 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20  urn it back off 
1fac0 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  again..*/.int sq
1fad0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
1fae0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69  d_extension(sqli
1faf0 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f  te3 *db, int ono
1fb00 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
1fb10 33 52 45 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e  3REF: Make Arran
1fb20 67 65 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d  gements To Autom
1fb30 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e  atically Load An
1fb40 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a   Extension.**.**
1fb50 20 52 65 67 69 73 74 65 72 20 61 6e 20 65 78 74   Register an ext
1fb60 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69  ension entry poi
1fb70 6e 74 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d  nt that is autom
1fb80 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64  atically invoked
1fb90 0a 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e  .** whenever a n
1fba0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1fbb0 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
1fbc0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1fbd0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1fbe0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
1fbf0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
1fc00 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  _v2()]..**.** Th
1fc10 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e  is API can be in
1fc20 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d  voked at program
1fc30 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65   startup in orde
1fc40 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  r to register.**
1fc50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61   one or more sta
1fc60 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65  tically linked e
1fc70 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77  xtensions that w
1fc80 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65  ill be available
1fc90 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64  .** to all new d
1fca0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fcb0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 44 75 70 6c 69  ons..**.** Dupli
1fcc0 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  cate extensions 
1fcd0 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20  are detected so 
1fce0 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  calling this rou
1fcf0 74 69 6e 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  tine multiple.**
1fd00 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
1fd10 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69  same extension i
1fd20 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a  s harmless..**.*
1fd30 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  * This routine s
1fd40 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20  tores a pointer 
1fd50 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  to the extension
1fd60 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20   in an array.** 
1fd70 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64  that is obtained
1fd80 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2e 20   from malloc(). 
1fd90 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65   If you run a me
1fda0 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20 63 68 65  mory leak.** che
1fdb0 63 6b 65 72 20 6f 6e 20 79 6f 75 72 20 70 72 6f  cker on your pro
1fdc0 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f  gram and it repo
1fdd0 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75  rts a leak becau
1fde0 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 61 72  se of this.** ar
1fdf0 72 61 79 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  ray, then invoke
1fe00 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d 61   [sqlite3_automa
1fe10 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e 5f 72 65  tic_extension_re
1fe20 73 65 74 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20  set()] prior.** 
1fe30 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66  to shutdown to f
1fe40 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a  ree the memory..
1fe50 2a 2a 0a 2a 2a 20 41 75 74 6f 6d 61 74 69 63 20  **.** Automatic 
1fe60 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79  extensions apply
1fe70 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65   across all thre
1fe80 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ads..**.** This 
1fe90 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70  interface is exp
1fea0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
1feb0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
1fec0 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c  ge or.** removal
1fed0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
1fee0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
1fef0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75  /.int sqlite3_au
1ff00 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
1ff10 64 20 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b  d *xEntryPoint);
1ff20 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
1ff30 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74  F: Reset Automat
1ff40 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  ic Extension Loa
1ff50 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 44 69 73 61 62  ding.**.** Disab
1ff60 6c 65 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c  le all previousl
1ff70 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74  y registered aut
1ff80 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
1ff90 73 2e 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74  s.  This.** rout
1ffa0 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
1ffb0 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69  ffect of all pri
1ffc0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f  or [sqlite3_auto
1ffd0 6d 61 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e 28  matic_extension(
1ffe0 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a  )].** calls..**.
1fff0 2a 2a 20 54 68 69 73 20 63 61 6c 6c 20 64 69 73  ** This call dis
20000 61 62 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 20  abled automatic 
20010 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c  extensions in al
20020 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a  l threads..**.**
20030 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
20040 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  is experimental 
20050 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74  and is subject t
20060 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72  o change or.** r
20070 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65  emoval in future
20080 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
20090 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ite..*/.void sql
200a0 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
200b0 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b  extension(void);
200c0 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50  .../*.****** EXP
200d0 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a  ERIMENTAL - subj
200e0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
200f0 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a  thout notice ***
20100 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a  ***********.**.*
20110 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
20120 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
20130 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
20140 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
20150 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
20160 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
20170 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
20180 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
20190 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
201a0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
201b0 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
201c0 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
201d0 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
201e0 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
201f0 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
20200 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
20210 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  tablizes, we wil
20220 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
20230 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
20240 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
20250 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
20260 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
20270 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74  nt..*/../*.** St
20280 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79  ructures used by
20290 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
202a0 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a  le interface.*/.
202b0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
202c0 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69  qlite3_vtab sqli
202d0 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65  te3_vtab;.typede
202e0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
202f0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69  _index_info sqli
20300 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a  te3_index_info;.
20310 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
20320 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
20330 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  or sqlite3_vtab_
20340 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20  cursor;.typedef 
20350 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
20360 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f  odule sqlite3_mo
20370 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 6d  dule;../*.** A m
20380 6f 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73  odule is a class
20390 20 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c   of virtual tabl
203a0 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65  es.  Each module
203b0 20 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62   is defined.** b
203c0 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  y an instance of
203d0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
203e0 74 72 75 63 74 75 72 65 2e 20 20 54 68 69 73 20  tructure.  This 
203f0 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73  structure consis
20400 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20  ts.** mostly of 
20410 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  methods for the 
20420 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63  module..*/.struc
20430 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
20440 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
20450 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61  n;.  int (*xCrea
20460 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  te)(sqlite3*, vo
20470 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
20480 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
20490 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
204a0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
204b0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
204c0 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
204d0 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
204e0 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69  (*xConnect)(sqli
204f0 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
20500 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
20510 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
20520 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
20530 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
20540 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
20550 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
20560 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49  ;.  int (*xBestI
20570 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74  ndex)(sqlite3_vt
20580 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
20590 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b  e3_index_info*);
205a0 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e  .  int (*xDiscon
205b0 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74  nect)(sqlite3_vt
205c0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
205d0 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71  t (*xDestroy)(sq
205e0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
205f0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65  b);.  int (*xOpe
20600 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
20610 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
20620 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70  vtab_cursor **pp
20630 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28  Cursor);.  int (
20640 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
20650 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
20660 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29    int (*xFilter)
20670 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
20680 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75  rsor*, int idxNu
20690 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69  m, const char *i
206a0 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20  dxStr,.         
206b0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
206c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
206d0 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a  *argv);.  int (*
206e0 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76  xNext)(sqlite3_v
206f0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
20700 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69  int (*xEof)(sqli
20710 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
20720 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75  );.  int (*xColu
20730 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  mn)(sqlite3_vtab
20740 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
20750 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
20760 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64  ;.  int (*xRowid
20770 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
20780 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
20790 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a  int64 *pRowid);.
207a0 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29    int (*xUpdate)
207b0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c  (sqlite3_vtab *,
207c0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61   int, sqlite3_va
207d0 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f  lue **, sqlite3_
207e0 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20  int64 *);.  int 
207f0 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65  (*xBegin)(sqlite
20800 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
20810 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
20820 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
20830 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  ab);.  int (*xCo
20840 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74  mmit)(sqlite3_vt
20850 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
20860 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73  t (*xRollback)(s
20870 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
20880 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ab);.  int (*xFi
20890 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69  ndFunction)(sqli
208a0 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
208b0 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74   int nArg, const
208c0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20   char *zName,.  
208d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
208e0 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46       void (**pxF
208f0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
20900 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
20910 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20  3_value**),.    
20920 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20930 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29     void **ppArg)
20940 3b 0a 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61  ;..  int (*xRena
20950 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  me)(sqlite3_vtab
20960 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63   *pVtab, const c
20970 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a  har *zNew);.};..
20980 2f 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  /*.** The sqlite
20990 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
209a0 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
209b0 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
209c0 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20  used to.** pass 
209d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f  information into
209e0 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65   and receive the
209f0 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20   reply from the 
20a00 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65  xBestIndex.** me
20a10 74 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74  thod of an sqlit
20a20 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  e3_module.  The 
20a30 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49  fields under **I
20a40 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a  nputs** are the.
20a50 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65  ** inputs to xBe
20a60 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20  stIndex and are 
20a70 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73  read-only.  xBes
20a80 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69  tIndex inserts i
20a90 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ts.** results in
20aa0 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73  to the **Outputs
20ab0 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a  ** fields..**.**
20ac0 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74   The aConstraint
20ad0 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73  [] array records
20ae0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
20af0 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65  nstraints of the
20b00 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20  .** form:.**.** 
20b10 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f          column O
20b20 50 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65  P expr.**.** Whe
20b30 72 65 20 4f 50 20 69 73 20 3d 2c 20 3c 2c 20 3c  re OP is =, <, <
20b40 3d 2c 20 3e 2c 20 6f 72 20 3e 3d 2e 20 20 54 68  =, >, or >=.  Th
20b50 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65  e particular ope
20b60 72 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a  rator is stored.
20b70 2a 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  ** in aConstrain
20b80 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64  t[].op.  The ind
20b90 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
20ba0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a   is stored in .*
20bb0 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  * aConstraint[].
20bc0 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74  iColumn.  aConst
20bd0 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69  raint[].usable i
20be0 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a  s TRUE if the.**
20bf0 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67   expr on the rig
20c00 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e  ht-hand side can
20c10 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61   be evaluated (a
20c20 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73  nd thus the cons
20c30 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61  traint.** is usa
20c40 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69  ble) and false i
20c50 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a  f it cannot..**.
20c60 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72  ** The optimizer
20c70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
20c80 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20  nverts terms of 
20c90 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f  the form "expr O
20ca0 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64  P column".** and
20cb0 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d   makes other sim
20cc0 70 6c 69 66 69 63 61 74 69 6e 6f 73 20 74 6f 20  plificatinos to 
20cd0 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
20ce0 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74   in an attempt t
20cf0 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79  o.** get as many
20d00 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
20d10 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72  rms into the for
20d20 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73  m shown above as
20d30 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68   possible..** Th
20d40 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
20d50 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72  array only repor
20d60 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ts WHERE clause 
20d70 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72  terms in the cor
20d80 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61  rect.** form tha
20d90 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70  t refer to the p
20da0 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61  articular virtua
20db0 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75  l table being qu
20dc0 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66  eried..**.** Inf
20dd0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
20de0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
20df0 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  se is stored in 
20e00 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45  aOrderBy[]..** E
20e10 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64  ach term of aOrd
20e20 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63  erBy records a c
20e30 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44  olumn of the ORD
20e40 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a  ER BY clause..**
20e50 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64  .** The xBestInd
20e60 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66  ex method must f
20e70 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  ill aConstraintU
20e80 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f  sage[] with info
20e90 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
20ea0 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73   what parameters
20eb0 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c   to pass to xFil
20ec0 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64  ter.  If argvInd
20ed0 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ex>0 then.** the
20ee0 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
20ef0 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   of the correspo
20f00 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e  nding aConstrain
20f10 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64  t[] is evaluated
20f20 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20  .** and becomes 
20f30 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68  the argvIndex-th
20f40 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20   entry in argv. 
20f50 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55   If aConstraintU
20f60 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69  sage[].omit.** i
20f70 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65  s true, then the
20f80 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61   constraint is a
20f90 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c  ssumed to be ful
20fa0 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68  ly handled by th
20fb0 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  e.** virtual tab
20fc0 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68  le and is not ch
20fd0 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53  ecked again by S
20fe0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
20ff0 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50   idxNum and idxP
21000 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65  tr values are re
21010 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65  corded and passe
21020 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a  d into xFilter..
21030 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
21040 29 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65  ) is used to fre
21050 65 20 69 64 78 50 74 72 20 69 66 20 6e 65 65 64  e idxPtr if need
21060 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20  ToFreeIdxPtr is 
21070 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  true..**.** The 
21080 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20  orderByConsumed 
21090 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75  means that outpu
210a0 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77  t from xFilter w
210b0 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20  ill occur in.** 
210c0 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65  the correct orde
210d0 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65  r to satisfy the
210e0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
210f0 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61   so that no sepa
21100 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20  rate.** sorting 
21110 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64  step is required
21120 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69  ..**.** The esti
21130 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
21140 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
21150 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
21160 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
21170 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
21180 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
21190 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
211a0 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
211b0 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
211c0 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
211d0 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
211e0 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
211f0 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
21200 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
21210 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
21220 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
21230 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
21240 75 74 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 69  uts */.  const i
21250 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20  nt nConstraint; 
21260 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
21270 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
21280 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 63 6f 6e  straint */.  con
21290 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
212a0 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
212b0 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  nt {.     int iC
212c0 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
212d0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e      /* Column on
212e0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
212f0 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  of constraint */
21300 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
21310 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20  har op;         
21320 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70  /* Constraint op
21330 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75  erator */.     u
21340 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61  nsigned char usa
21350 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65  ble;     /* True
21360 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61   if this constra
21370 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f  int is usable */
21380 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f  .     int iTermO
21390 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20  ffset;          
213a0 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c  /* Used internal
213b0 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20  ly - xBestIndex 
213c0 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f  should ignore */
213d0 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e  .  } *const aCon
213e0 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 2f 2a  straint;      /*
213f0 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20   Table of WHERE 
21400 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
21410 74 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e  ts */.  const in
21420 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20  t nOrderBy;     
21430 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
21440 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44  terms in the ORD
21450 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
21460 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
21470 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64  qlite3_index_ord
21480 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20  erby {.     int 
21490 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20  iColumn;        
214a0 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20        /* Column 
214b0 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75  number */.     u
214c0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73  nsigned char des
214d0 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65  c;       /* True
214e0 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73   for DESC.  Fals
214f0 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20  e for ASC. */.  
21500 7d 20 2a 63 6f 6e 73 74 20 61 4f 72 64 65 72 42  } *const aOrderB
21510 79 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68  y;         /* Th
21520 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
21530 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f 75 74 70 75  e */..  /* Outpu
21540 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  ts */.  struct s
21550 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
21560 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a  straint_usage {.
21570 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
21580 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  x;           /* 
21590 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e  if >0, constrain
215a0 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67  t is part of arg
215b0 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a  v to xFilter */.
215c0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
215d0 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20  r omit;      /* 
215e0 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65  Do not code a te
215f0 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73  st for this cons
21600 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 63  traint */.  } *c
21610 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74  onst aConstraint
21620 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78  Usage;.  int idx
21630 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20  Num;            
21640 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73      /* Number us
21650 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74  ed to identify t
21660 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68  he index */.  ch
21670 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20  ar *idxStr;     
21680 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69           /* Stri
21690 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74  ng, possibly obt
216a0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
216b0 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69  e3_malloc */.  i
216c0 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  nt needToFreeIdx
216d0 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65  Str;      /* Fre
216e0 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73  e idxStr using s
216f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66  qlite3_free() if
21700 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f   true */.  int o
21710 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20  rderByConsumed; 
21720 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66        /* True if
21730 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61   output is alrea
21740 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20  dy ordered */.  
21750 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64  double estimated
21760 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73  Cost;      /* Es
21770 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20  timated cost of 
21780 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78  using this index
21790 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53   */.};.#define S
217a0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
217b0 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23  TRAINT_EQ    2.#
217c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
217d0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
217e0 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53  T    4.#define S
217f0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
21800 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23  TRAINT_LE    8.#
21810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
21820 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
21830 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20  T    16.#define 
21840 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
21850 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32  STRAINT_GE    32
21860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21870 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
21880 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a  _MATCH 64../*.**
21890 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
218a0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
218b0 72 20 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e  r a new module n
218c0 61 6d 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69  ame with an SQLi
218d0 74 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  te.** connection
218e0 2e 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20  .  Module names 
218f0 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72  must be register
21900 65 64 20 62 65 66 6f 72 65 20 63 72 65 61 74 69  ed before creati
21910 6e 67 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61  ng new.** virtua
21920 6c 20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20  l tables on the 
21930 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72  module, or befor
21940 65 20 75 73 69 6e 67 20 70 72 65 65 78 69 73 74  e using preexist
21950 69 6e 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74  ing virtual.** t
21960 61 62 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64  ables of the mod
21970 75 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ule..*/.int sqli
21980 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
21990 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
219a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
219b0 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
219c0 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
219d0 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
219e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
219f0 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
21a00 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
21a10 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
21a20 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20  lite3_module *, 
21a30 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
21a40 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
21a50 20 20 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20    void *        
21a60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
21a70 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
21a80 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
21a90 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68   */.);../*.** Th
21aa0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64  is routine is id
21ab0 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73  entical to the s
21ac0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
21ad0 64 75 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62  dule() method ab
21ae0 6f 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74  ove,.** except t
21af0 68 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20  hat it allows a 
21b00 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
21b10 69 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66  ion to be specif
21b20 69 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76  ied. It is.** ev
21b30 65 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65  en more experime
21b40 6e 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65  ntal than the re
21b50 73 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  st of the virtua
21b60 6c 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f  l tables API..*/
21b70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
21b80 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20  ate_module_v2(. 
21b90 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
21ba0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
21bb0 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
21bc0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
21bd0 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
21be0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
21bf0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
21c00 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
21c10 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
21c20 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f  3_module *,    /
21c30 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
21c40 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
21c50 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
21c60 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
21c70 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
21c80 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
21c90 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
21ca0 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20  )(void*)     /* 
21cb0 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f  Module destructo
21cc0 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b  r function */.);
21cd0 0a 0a 2f 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f  ../*.** Every mo
21ce0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
21cf0 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
21d00 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  ass of the follo
21d10 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a  wing structure.*
21d20 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20  * to describe a 
21d30 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61  particular insta
21d40 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  nce of the modul
21d50 65 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73  e.  Each subclas
21d60 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 79  s will.** be tay
21d70 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65  lored to the spe
21d80 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74  cific needs of t
21d90 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  he module implem
21da0 65 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a  entation.   The.
21db0 2a 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68  ** purpose of th
21dc0 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73  is superclass is
21dd0 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61   to define certa
21de0 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61  in fields that a
21df0 72 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20  re common.** to 
21e00 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  all module imple
21e10 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  mentations..**.*
21e20 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
21e30 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74   methods can set
21e40 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
21e50 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61  e by assigning a
21e60 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69  .** string obtai
21e70 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
21e80 5f 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45  _mprintf() to zE
21e90 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68  rrMsg.  The meth
21ea0 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b  od should.** tak
21eb0 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20  e care that any 
21ec0 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20  prior string is 
21ed0 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20  freed by a call 
21ee0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
21ef0 29 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73  ).** prior to as
21f00 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74  signing a new st
21f10 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e  ring to zErrMsg.
21f20 20 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f    After the erro
21f30 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20  r message.** is 
21f40 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20  delivered up to 
21f50 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69  the client appli
21f60 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69  cation, the stri
21f70 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ng will be autom
21f80 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65  atically.** free
21f90 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65  d by sqlite3_fre
21fa0 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72  e() and the zErr
21fb0 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62  Msg field will b
21fc0 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a  e zeroed.  Note.
21fd0 2a 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  ** that sqlite3_
21fe0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
21ff0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 65  lite3_free() are
22000 20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72   used on the zEr
22010 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69  rMsg field.** si
22020 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  nce virtual tabl
22030 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20  es are commonly 
22040 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c  implemented in l
22050 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f  oadable extensio
22060 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e  ns which.** do n
22070 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 20 74  ot have access t
22080 6f 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66  o sqlite3MPrintf
22090 28 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65  () or sqlite3Fre
220a0 65 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  e()..*/.struct s
220b0 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20  qlite3_vtab {.  
220c0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
220d0 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20  dule *pModule;  
220e0 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f  /* The module fo
220f0 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74  r this virtual t
22100 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52  able */.  int nR
22110 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ef;             
22120 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
22130 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a  d internally */.
22140 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b    char *zErrMsg;
22150 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22160 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61    /* Error messa
22170 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ge from sqlite3_
22180 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f  mprintf() */.  /
22190 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
221a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
221b0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
221c0 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
221d0 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45  elds */.};../* E
221e0 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  very module impl
221f0 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
22200 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
22210 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  e following stru
22220 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63  cture.** to desc
22230 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61  ribe cursors tha
22240 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65  t point into the
22250 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
22260 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74  nd are used.** t
22270 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74  o loop through t
22280 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
22290 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63  .  Cursors are c
222a0 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
222b0 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  .** xOpen method
222c0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
222d0 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70   Each module imp
222e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
222f0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63   define.** the c
22300 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73  ontent of a curs
22310 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  or structure to 
22320 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65  suit its own nee
22330 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  ds..**.** This s
22340 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73  uperclass exists
22350 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66   in order to def
22360 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ine fields of th
22370 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a  e cursor that.**
22380 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61   are common to a
22390 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ll implementatio
223a0 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ns..*/.struct sq
223b0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
223c0 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74  r {.  sqlite3_vt
223d0 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20  ab *pVtab;      
223e0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
223f0 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20   of this cursor 
22400 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
22410 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
22420 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
22430 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
22440 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
22450 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65  ../*.** The xCre
22460 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74  ate and xConnect
22470 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f   methods of a mo
22480 64 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c  dule use the fol
22490 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f  lowing API.** to
224a0 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72   declare the for
224b0 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61  mat (the names a
224c0 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20  nd datatypes of 
224d0 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a  the columns) of.
224e0 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  ** the virtual t
224f0 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65  ables they imple
22500 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ment..*/.int sql
22510 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61  ite3_declare_vta
22520 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73  b(sqlite3*, cons
22530 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54  t char *zCreateT
22540 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69  able);../*.** Vi
22550 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e  rtual tables can
22560 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61   provide alterna
22570 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tive implementat
22580 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e  ions of function
22590 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78  s.** using the x
225a0 46 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74  FindFunction met
225b0 68 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c  hod.  But global
225c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f   versions of tho
225d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  se functions.** 
225e0 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72  must exist in or
225f0 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f  der to be overlo
22600 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  aded..**.** This
22610 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20   API makes sure 
22620 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  a global version
22630 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77   of a function w
22640 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
22650 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d  .** name and num
22660 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72  ber of parameter
22670 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f  s exists.  If no
22680 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65   such function e
22690 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20  xists.** before 
226a0 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c  this API is call
226b0 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69  ed, a new functi
226c0 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20 20  on is created.  
226d0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
226e0 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77  on.** of the new
226f0 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73   function always
22700 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70   causes an excep
22710 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77  tion to be throw
22720 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65  n.  So.** the ne
22730 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f  w function is no
22740 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68  t good for anyth
22750 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20  ing by itself.  
22760 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70  Its only.** purp
22770 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70  ose is to be a p
22780 6c 61 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63  lace-holder func
22790 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65  tion that can be
227a0 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62   overloaded.** b
227b0 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  y virtual tables
227c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
227d0 20 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69   should be consi
227e0 64 65 72 65 64 20 70 61 72 74 20 6f 66 20 74 68  dered part of th
227f0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
22800 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68  interface,.** wh
22810 69 63 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e  ich is experimen
22820 74 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20  tal and subject 
22830 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  to change..*/.in
22840 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f  t sqlite3_overlo
22850 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69  ad_function(sqli
22860 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
22870 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74   *zFuncName, int
22880 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54   nArg);../*.** T
22890 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
228a0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
228b0 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69  e mechanism defi
228c0 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20  ned above (back 
228d0 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65  up.** to a comme
228e0 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69  nt remarkably si
228f0 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e  milar to this on
22900 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  e) is currently 
22910 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f  considered.** to
22920 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   be experimental
22930 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
22940 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
22950 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61   incompatible wa
22960 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69  ys..** If this i
22970 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20  s a problem for 
22980 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20  you, do not use 
22990 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74  the interface at
229a0 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a   this time..**.*
229b0 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75  * When the virtu
229c0 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
229d0 73 6d 20 73 74 61 62 6c 69 7a 65 73 2c 20 77 65  sm stablizes, we
229e0 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
229f0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
22a00 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
22a10 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
22a20 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
22a30 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a  omment..**.*****
22a40 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d  * EXPERIMENTAL -
22a50 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
22a60 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63  ge without notic
22a70 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e **************
22a80 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .*/../*.** CAPI3
22a90 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f  REF: A Handle To
22aa0 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a   An Open BLOB.**
22ab0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
22ac0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
22ad0 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72   opaque structur
22ae0 65 20 69 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a  e is used to .**
22af0 20 72 65 70 72 65 73 65 6e 74 20 61 6e 20 62 6c   represent an bl
22b00 6f 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62 6c  ob-handle.  A bl
22b10 6f 62 2d 68 61 6e 64 6c 65 20 69 73 20 63 72 65  ob-handle is cre
22b20 61 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  ated by.** [sqli
22b30 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
22b40 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62   and destroyed b
22b50 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
22b60 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  close()]..** The
22b70 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
22b80 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
22b90 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
22ba0 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
22bb0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
22bc0 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
22bd0 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
22be0 66 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54  f the blob..** T
22bf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
22c00 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
22c10 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
22c20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62  size of the.** b
22c30 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  lob in bytes..*/
22c40 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
22c50 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
22c60 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
22c70 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
22c80 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
22c90 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a  emental I/O.**.*
22ca0 2a 20 4f 70 65 6e 20 61 20 68 61 6e 64 6c 65 20  * Open a handle 
22cb0 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f 63 61  to the blob loca
22cc0 74 65 64 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c  ted in row iRow,
22cd0 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e  , column zColumn
22ce0 2c 20 0a 2a 2a 20 74 61 62 6c 65 20 7a 54 61 62  , .** table zTab
22cf0 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a  le in database z
22d00 44 62 2e 20 69 2e 65 2e 20 74 68 65 20 73 61 6d  Db. i.e. the sam
22d10 65 20 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c  e blob that woul
22d20 64 0a 2a 2a 20 62 65 20 73 65 6c 65 63 74 65 64  d.** be selected
22d30 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e   by:.**.** <pre>
22d40 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a  .**     SELECT z
22d50 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e  Column FROM zDb.
22d60 7a 54 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77  zTable WHERE row
22d70 69 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f  id = iRow;.** </
22d80 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  pre>.**.** If th
22d90 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
22da0 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  r is non-zero, t
22db0 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65  he blob is opene
22dc0 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61  d for .** read a
22dd0 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e  nd write access.
22de0 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20   If it is zero, 
22df0 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e  the blob is open
22e00 65 64 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20  ed for read .** 
22e10 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  access..**.** On
22e20 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
22e30 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
22e40 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a  d and the new .*
22e50 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
22e60 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69  | blob handle] i
22e70 73 20 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70  s written to *pp
22e80 42 6c 6f 62 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  Blob..** Otherwi
22e90 73 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  se an error code
22ea0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
22eb0 20 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 77   .** any value w
22ec0 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f  ritten to *ppBlo
22ed0 62 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  b should not be 
22ee0 75 73 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c  used by the call
22ef0 65 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  er..** This func
22f00 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61  tion sets the da
22f10 74 61 62 61 73 65 2d 68 61 6e 64 6c 65 20 65 72  tabase-handle er
22f20 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
22f30 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62  sage.** accessib
22f40 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  le via [sqlite3_
22f50 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b  errcode()] and [
22f60 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
22f70 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
22f80 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73  3_blob_open(.  s
22f90 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74  qlite3*,.  const
22fa0 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f   char *zDb,.  co
22fb0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
22fc0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
22fd0 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74  zColumn,.  sqlit
22fe0 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20  e3_int64 iRow,. 
22ff0 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71   int flags,.  sq
23000 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42  lite3_blob **ppB
23010 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lob.);../*.** CA
23020 50 49 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41  PI3REF:  Close A
23030 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a   BLOB Handle.**.
23040 2a 2a 20 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e  ** Close an open
23050 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
23060 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a   blob handle]..*
23070 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
23080 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  ob_close(sqlite3
23090 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
230a0 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 74 75   CAPI3REF:  Retu
230b0 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41  rn The Size Of A
230c0 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a  n Open BLOB.**.*
230d0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
230e0 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68  e in bytes of th
230f0 65 20 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c  e blob accessibl
23100 65 20 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a  e via the open .
23110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
23120 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20   | blob-handle] 
23130 70 61 73 73 65 64 20 61 73 20 61 6e 20 61 72 67  passed as an arg
23140 75 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ument..*/.int sq
23150 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
23160 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
23170 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23180 46 3a 20 20 52 65 61 64 20 44 61 74 61 20 46 72  F:  Read Data Fr
23190 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  om A BLOB Increm
231a0 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68  entally.**.** Th
231b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
231c0 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61  sed to read data
231d0 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a   from an open .*
231e0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
231f0 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69  | blob-handle] i
23200 6e 74 6f 20 61 20 63 61 6c 6c 65 72 20 73 75 70  nto a caller sup
23210 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a  plied buffer..**
23220 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   n bytes of data
23230 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
23240 20 62 75 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f   buffer.** z fro
23250 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c  m the open blob,
23260 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
23270 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
23280 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53  ** On success, S
23290 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
232a0 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c  rned. Otherwise,
232b0 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   an .** [SQLITE_
232c0 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65  ERROR | SQLite e
232d0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e  rror code] or an
232e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
232f0 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
23300 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
23310 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e   returned..*/.in
23320 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  t sqlite3_blob_r
23330 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ead(sqlite3_blob
23340 20 2a 2c 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74   *, void *z, int
23350 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   n, int iOffset)
23360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23370 46 3a 20 20 57 72 69 74 65 20 44 61 74 61 20 49  F:  Write Data I
23380 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65  nto A BLOB Incre
23390 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54  mentally.**.** T
233a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
233b0 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61  used to write da
233c0 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20  ta into an open 
233d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
233e0 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d  b | blob-handle]
233f0 20 66 72 6f 6d 20 61 20 75 73 65 72 20 73 75 70   from a user sup
23400 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a  plied buffer..**
23410 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   n bytes of data
23420 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d   are copied from
23430 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 70   the buffer.** p
23440 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 7a 20 69  ointed to by z i
23450 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f  nto the open blo
23460 62 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f  b, starting at o
23470 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a  ffset iOffset..*
23480 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
23490 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
234a0 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20  -handle] passed 
234b0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
234c0 75 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74  ument.** was not
234d0 20 6f 70 65 6e 65 64 20 66 6f 72 20 77 72 69 74   opened for writ
234e0 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70  ing (the flags p
234f0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
23500 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
23510 5d 0a 2a 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c  ].*** was zero),
23520 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
23530 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
23540 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20  EADONLY]..**.** 
23550 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
23560 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68  y only modify th
23570 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68  e contents of th
23580 65 20 62 6c 6f 62 2c 20 69 74 20 69 73 0a 2a 2a  e blob, it is.**
23590 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
235a0 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69   increase the si
235b0 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 75 73 69  ze of a blob usi
235c0 6e 67 20 74 68 69 73 20 41 50 49 2e 20 49 66 0a  ng this API. If.
235d0 2a 2a 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  ** offset iOffse
235e0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6e  t is less than n
235f0 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
23600 65 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c  end of the blob,
23610 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
23620 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
23630 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
23640 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ritten..**.** On
23650 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45   success, SQLITE
23660 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
23670 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a   Otherwise, an .
23680 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
23690 20 7c 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20   | SQLite error 
236a0 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
236b0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
236c0 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72  D | extended err
236d0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
236e0 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rned..*/.int sql
236f0 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
23700 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
23710 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69  const void *z, i
23720 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65  nt n, int iOffse
23730 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
23740 52 45 46 3a 20 20 56 69 72 74 75 61 6c 20 46 69  REF:  Virtual Fi
23750 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
23760 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  s.**.** A virtua
23770 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46  l filesystem (VF
23780 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65  S) is an [sqlite
23790 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a  3_vfs] object.**
237a0 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65   that SQLite use
237b0 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a  s to interact.**
237c0 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c   with the underl
237d0 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
237e0 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69  ystem.  Most bui
237f0 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a  lds come with a.
23800 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c  ** single defaul
23810 74 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70  t VFS that is ap
23820 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68  propriate for th
23830 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
23840 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61  .** New VFSes ca
23850 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
23860 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53  and existing VFS
23870 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69  es can be unregi
23880 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66  stered..** The f
23890 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61  ollowing interfa
238a0 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
238b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
238c0 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69  te3_vfs_find() i
238d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
238e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
238f0 56 46 53 20 67 69 76 65 6e 20 69 74 73 0a 2a 2a  VFS given its.**
23900 20 6e 61 6d 65 2e 20 20 4e 61 6d 65 73 20 61 72   name.  Names ar
23910 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65  e case sensitive
23920 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
23930 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a  o match, a NULL.
23940 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  ** pointer is re
23950 74 75 72 6e 65 64 2e 20 20 49 66 20 7a 56 66 73  turned.  If zVfs
23960 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65  Name is NULL the
23970 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 0a 2a  n the default .*
23980 2a 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65  * VFS is returne
23990 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53  d..**.** New VFS
239a0 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  es are registere
239b0 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76  d with sqlite3_v
239c0 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 20 20  fs_register().  
239d0 45 61 63 68 0a 2a 2a 20 6e 65 77 20 56 46 53 20  Each.** new VFS 
239e0 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
239f0 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
23a00 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
23a10 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65  set..** The same
23a20 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69   VFS can be regi
23a30 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
23a40 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e  times without in
23a50 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65  jury..** To make
23a60 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53   an existing VFS
23a70 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c   into the defaul
23a80 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20  t VFS, register 
23a90 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68  it again.** with
23aa0 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
23ab0 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20  ag set.  If two 
23ac0 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20  different VFSes 
23ad0 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65  with the.** same
23ae0 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74   name are regist
23af0 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69  ered, the behavi
23b00 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
23b10 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73    If a.** VFS is
23b20 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
23b30 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20   a name that is 
23b40 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
23b50 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e   string,.** then
23b60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
23b70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a   undefined..** .
23b80 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20  ** Unregister a 
23b90 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c  VFS with the sql
23ba0 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
23bb0 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  ter() interface.
23bc0 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75  .** If the defau
23bd0 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69  lt VFS is unregi
23be0 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20  stered, another 
23bf0 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73  VFS is chosen as
23c00 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e  .** the default.
23c10 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72    The choice for
23c20 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20   the new VFS is 
23c30 61 72 62 69 74 72 61 72 79 2e 0a 2a 2f 0a 73 71  arbitrary..*/.sq
23c40 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74  lite3_vfs *sqlit
23c50 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73  e3_vfs_find(cons
23c60 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65  t char *zVfsName
23c70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
23c80 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69  fs_register(sqli
23c90 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61  te3_vfs*, int ma
23ca0 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c  keDflt);.int sql
23cb0 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
23cc0 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ter(sqlite3_vfs*
23cd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23ce0 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a  EF: Mutexes.**.*
23cf0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
23d00 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  e uses these rou
23d10 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64  tines for thread
23d20 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74  .** synchronizat
23d30 69 6f 6e 2e 20 20 54 68 6f 75 67 68 20 74 68 65  ion.  Though the
23d40 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  y are intended f
23d50 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75  or internal.** u
23d60 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f  se by SQLite, co
23d70 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  de that links ag
23d80 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a  ainst SQLite is.
23d90 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  ** permitted to 
23da0 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  use any of these
23db0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
23dc0 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72   The SQLite sour
23dd0 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73  ce code contains
23de0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
23df0 65 6e 74 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66  entations .** of
23e00 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75   these mutex rou
23e10 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f  tines.  An appro
23e20 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74  priate implement
23e30 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65  ation.** is sele
23e40 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  cted automatical
23e50 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ly at compile-ti
23e60 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  me.  The followi
23e70 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ng.** implementa
23e80 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61  tions are availa
23e90 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ble in the SQLit
23ea0 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  e core:.**.** <u
23eb0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  l>.** <li>   SQL
23ec0 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a  ITE_MUTEX_OS2.**
23ed0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
23ee0 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20  UTEX_PTHREAD.** 
23ef0 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
23f00 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20  TEX_W32.** <li> 
23f10 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e    SQLITE_MUTEX_N
23f20 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  OOP.** </ul>.**.
23f30 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55  ** The SQLITE_MU
23f40 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65  TEX_NOOP impleme
23f50 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74  ntation is a set
23f60 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a   of routines .**
23f70 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65   that does no re
23f80 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69  al locking and i
23f90 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
23fa0 72 20 75 73 65 20 69 6e 20 0a 2a 2a 20 61 20 73  r use in .** a s
23fb0 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61  ingle-threaded a
23fc0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
23fd0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53   SQLITE_MUTEX_OS
23fe0 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  2,.** SQLITE_MUT
23ff0 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20  EX_PTHREAD, and 
24000 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32  SQLITE_MUTEX_W32
24010 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
24020 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69  .** are appropri
24030 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 6f  ate for use on o
24040 73 2f 32 2c 20 75 6e 69 78 2c 20 61 6e 64 20 77  s/2, unix, and w
24050 69 6e 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49  indows..** .** I
24060 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
24070 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  iled with the SQ
24080 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45  LITE_MUTEX_APPDE
24090 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a  F preprocessor.*
240a0 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20  * macro defined 
240b0 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f  (with "-DSQLITE_
240c0 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29  MUTEX_APPDEF=1")
240d0 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a  , then no mutex.
240e0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
240f0 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69  n is included wi
24100 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20  th the library. 
24110 20 54 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e   The.** mutex in
24120 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
24130 20 64 65 66 69 6e 65 64 20 68 65 72 65 20 62 65   defined here be
24140 63 6f 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a  come external.**
24150 20 72 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74   references in t
24160 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
24170 79 20 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c  y for which impl
24180 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d  ementations.** m
24190 75 73 74 20 62 65 20 70 72 6f 76 69 64 65 64 20  ust be provided 
241a0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
241b0 6f 6e 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69  on.  This facili
241c0 74 79 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20  ty allows an.** 
241d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74  application that
241e0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53   links against S
241f0 51 4c 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65  QLite to provide
24200 20 69 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a   its own mutex.*
24210 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
24220 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20   without having 
24230 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  to modify the SQ
24240 4c 69 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a  Lite core..**.**
24250 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
24260 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  ex_alloc() routi
24270 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e  ne allocates a n
24280 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20  ew.** mutex and 
24290 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
242a0 72 20 74 6f 20 69 74 2e 20 20 49 66 20 69 74 20  r to it.  If it 
242b0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20  returns NULL.** 
242c0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20  that means that 
242d0 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f  a mutex could no
242e0 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20  t be allocated. 
242f0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
24300 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b  unwind its stack
24310 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65   and return an e
24320 72 72 6f 72 2e 20 20 54 68 65 20 61 72 67 75 6d  rror.  The argum
24330 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
24340 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
24350 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  is one of these 
24360 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
24370 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
24380 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
24390 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e  TEX_FAST.** <li>
243a0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52    SQLITE_MUTEX_R
243b0 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  ECURSIVE.** <li>
243c0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
243d0 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20  TATIC_MASTER.** 
243e0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
243f0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a  EX_STATIC_MEM.**
24400 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
24410 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a  TEX_STATIC_MEM2.
24420 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
24430 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
24440 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  G.** <li>  SQLIT
24450 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
24460 52 55 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  RU.** </ul>.**.*
24470 2a 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20  * The first two 
24480 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20  constants cause 
24490 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
244a0 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a  loc() to create.
244b0 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20  ** a new mutex. 
244c0 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69   The new mutex i
244d0 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e  s recursive when
244e0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
244f0 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73  CURSIVE.** is us
24500 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73  ed but not neces
24510 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53  sarily so when S
24520 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
24530 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65   is used..** The
24540 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
24550 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
24560 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69  eed to make a di
24570 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
24580 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  ween SQLITE_MUTE
24590 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20  X_RECURSIVE and 
245a0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
245b0 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20  T if it does.** 
245c0 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 42 75  not want to.  Bu
245d0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e  t SQLite will on
245e0 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63  ly request a rec
245f0 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a  ursive mutex in.
24600 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69  ** cases where i
24610 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f  t really needs o
24620 6e 65 2e 20 20 49 66 20 61 20 66 61 73 74 65 72  ne.  If a faster
24630 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d   non-recursive m
24640 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
24650 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  tation is availa
24660 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20  ble on the host 
24670 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75  platform, the mu
24680 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a  tex subsystem.**
24690 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75   might return su
246a0 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65  ch a mutex in re
246b0 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45  sponse to SQLITE
246c0 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a  _MUTEX_FAST..**.
246d0 2a 2a 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c  ** The other all
246e0 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  owed parameters 
246f0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
24700 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65  _alloc() each re
24710 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  turn.** a pointe
24720 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72  r to a static pr
24730 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e  eexisting mutex.
24740 20 20 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75    Four static mu
24750 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  texes are.** use
24760 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  d by the current
24770 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
24780 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  te.  Future vers
24790 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
247a0 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69  * may add additi
247b0 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65  onal static mute
247c0 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74  xes.  Static mut
247d0 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74  exes are for int
247e0 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
247f0 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70  SQLite only.  Ap
24800 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
24810 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78  use SQLite mutex
24820 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65  es should.** use
24830 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69   only the dynami
24840 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e  c mutexes return
24850 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54  ed by SQLITE_MUT
24860 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51  EX_FAST or.** SQ
24870 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
24880 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  SIVE..**.** Note
24890 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20   that if one of 
248a0 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  the dynamic mute
248b0 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51  x parameters (SQ
248c0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a  LITE_MUTEX_FAST.
248d0 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54  ** or SQLITE_MUT
248e0 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73  EX_RECURSIVE) is
248f0 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74   used then sqlit
24900 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
24910 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69  .** returns a di
24920 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e  fferent mutex on
24930 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 42 75   every call.  Bu
24940 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63  t for the static
24950 20 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73   .** mutex types
24960 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78  , the same mutex
24970 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20   is returned on 
24980 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20  every call that 
24990 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  has.** the same 
249a0 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  type number..**.
249b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
249c0 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74  utex_free() rout
249d0 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  ine deallocates 
249e0 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  a previously.** 
249f0 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69  allocated dynami
24a00 63 20 6d 75 74 65 78 2e 20 20 53 51 4c 69 74 65  c mutex.  SQLite
24a10 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64   is careful to d
24a20 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a  eallocate every.
24a30 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ** dynamic mutex
24a40 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74   that it allocat
24a50 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63  es.  The dynamic
24a60 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f   mutexes must no
24a70 74 20 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65 20  t be in .** use 
24a80 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65  when they are de
24a90 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65  allocated.  Atte
24aa0 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f  mpting to deallo
24ab0 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a  cate a static.**
24ac0 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69   mutex results i
24ad0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
24ae0 76 69 6f 72 2e 20 20 53 51 4c 69 74 65 20 6e 65  vior.  SQLite ne
24af0 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a  ver deallocates.
24b00 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65  ** a static mute
24b10 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  x..**.** The sql
24b20 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
24b30 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
24b40 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69  utex_try() routi
24b50 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74  nes attempt.** t
24b60 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e  o enter a mutex.
24b70 20 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72    If another thr
24b80 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77  ead is already w
24b90 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c  ithin the mutex,
24ba0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
24bb0 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62  x_enter() will b
24bc0 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33  lock and sqlite3
24bd0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c  _mutex_try() wil
24be0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  l return.** SQLI
24bf0 54 45 5f 42 55 53 59 2e 20 20 54 68 65 20 73 71  TE_BUSY.  The sq
24c00 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
24c10 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
24c20 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a  rns SQLITE_OK.**
24c30 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c   upon successful
24c40 20 65 6e 74 72 79 2e 20 20 4d 75 74 65 78 65 73   entry.  Mutexes
24c50 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 53   created using S
24c60 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
24c70 52 53 49 56 45 20 63 61 6e 0a 2a 2a 20 62 65 20  RSIVE can.** be 
24c80 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  entered multiple
24c90 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61   times by the sa
24ca0 6d 65 20 74 68 72 65 61 64 2e 20 20 49 6e 20 73  me thread.  In s
24cb0 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a  uch cases the,.*
24cc0 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20  * mutex must be 
24cd0 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20  exited an equal 
24ce0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
24cf0 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74  before another t
24d00 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74  hread.** can ent
24d10 65 72 2e 20 20 49 66 20 74 68 65 20 73 61 6d 65  er.  If the same
24d20 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f   thread tries to
24d30 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72   enter any other
24d40 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 0a 2a   kind of mutex.*
24d50 2a 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  * more than once
24d60 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
24d70 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 20 53  s undefined.   S
24d80 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
24d90 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68   exhibit.** such
24da0 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73   behavior in its
24db0 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65   own use of mute
24dc0 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  xes..**.** Some 
24dd0 73 79 73 74 65 6d 73 20 28 65 78 3a 20 77 69 6e  systems (ex: win
24de0 64 6f 77 73 39 35 29 20 64 6f 20 6e 6f 74 20 74  dows95) do not t
24df0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 6d 70  he operation imp
24e00 6c 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 73  lemented by.** s
24e10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
24e20 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79  ().  On those sy
24e30 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d  stems, sqlite3_m
24e40 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 0a  utex_try() will.
24e50 2a 2a 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ** always return
24e60 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54   SQLITE_BUSY.  T
24e70 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f  he SQLite core o
24e80 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a  nly ever uses.**
24e90 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
24ea0 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d  ry() as an optim
24eb0 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20  ization so this 
24ec0 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65  is acceptable be
24ed0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  havior..**.** Th
24ee0 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
24ef0 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20  leave() routine 
24f00 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 68  exits a mutex th
24f10 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  at was.** previo
24f20 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20  usly entered by 
24f30 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
24f40 20 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a    The behavior.*
24f50 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69  * is undefined i
24f60 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e  f the mutex is n
24f70 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ot currently ent
24f80 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63  ered by the.** c
24f90 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72  alling thread or
24fa0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
24fb0 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51  y allocated.  SQ
24fc0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76  Lite will.** nev
24fd0 65 72 20 64 6f 20 65 69 74 68 65 72 2e 0a 2a 2a  er do either..**
24fe0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
24ff0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
25000 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
25010 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
25020 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  )]..*/.sqlite3_m
25030 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75  utex *sqlite3_mu
25040 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  tex_alloc(int);.
25050 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74  void sqlite3_mut
25060 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f  ex_free(sqlite3_
25070 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
25080 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
25090 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  r(sqlite3_mutex*
250a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  );.int sqlite3_m
250b0 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33  utex_try(sqlite3
250c0 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73  _mutex*);.void s
250d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
250e0 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ve(sqlite3_mutex
250f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
25100 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66  REF: Mutex Verif
25110 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
25120 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
25130 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61  3_mutex_held() a
25140 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
25150 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69  _notheld() routi
25160 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e  nes.** are inten
25170 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ded for use insi
25180 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74  de assert() stat
25190 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 53 51 4c  ements.  The SQL
251a0 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65  ite core.** neve
251b0 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  r uses these rou
251c0 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73  tines except ins
251d0 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20  ide an assert() 
251e0 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  and applications
251f0 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20  .** are advised 
25200 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65  to follow the le
25210 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20  ad of the core. 
25220 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a   The core only.*
25230 2a 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65  * provides imple
25240 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74  mentations for t
25250 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68  hese routines wh
25260 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
25270 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51  d.** with the SQ
25280 4c 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e  LITE_DEBUG flag.
25290 20 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78    External mutex
252a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
252b0 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71  .** are only req
252c0 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65  uired to provide
252d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
252e0 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20  if SQLITE_DEBUG 
252f0 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e  is.** defined an
25300 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e  d if NDEBUG is n
25310 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ot defined..**.*
25320 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
25330 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
25340 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 78  rue if the mutex
25350 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65   in their argume
25360 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72  nt.** is held or
25370 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65   not held, respe
25380 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20  ctively, by the 
25390 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a  calling thread..
253a0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d  **.** The implem
253b0 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  entation is not 
253c0 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76  required to prov
253d0 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66  ided versions of
253e0 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e   these.** routin
253f0 65 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79  es that actually
25400 20 77 6f 72 6b 2e 0a 2a 2a 20 49 66 20 74 68 65   work..** If the
25410 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25420 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65  does not provide
25430 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73   working.** vers
25440 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f  ions of these ro
25450 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c  utines, it shoul
25460 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69  d at least provi
25470 64 65 20 73 74 75 62 73 0a 2a 2a 20 74 68 61 74  de stubs.** that
25480 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
25490 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20  rue so that one 
254a0 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75  does not get spu
254b0 72 69 6f 75 73 0a 2a 2a 20 61 73 73 65 72 74 69  rious.** asserti
254c0 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a  on failures..**.
254d0 2a 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65  ** If the argume
254e0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  nt to sqlite3_mu
254f0 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61 20  tex_held() is a 
25500 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
25510 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65  n.** the routine
25520 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 31   should return 1
25530 2e 20 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f  .  This seems co
25540 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20  unter-intuitive 
25550 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79  since.** clearly
25560 20 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f   the mutex canno
25570 74 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20  t be held if it 
25580 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20  does not exist. 
25590 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20   But the.** the 
255a0 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78  reason the mutex
255b0 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
255c0 69 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62  is because the b
255d0 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75  uild is not.** u
255e0 73 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41  sing mutexes.  A
255f0 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e  nd we do not wan
25600 74 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63  t the assert() c
25610 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
25620 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
25630 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f  _mutex_held() to
25640 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d   fail, so a non-
25650 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a  zero return is.*
25660 2a 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  * the appropriat
25670 65 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20  e thing to do.  
25680 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
25690 78 5f 6e 6f 74 68 65 6c 64 28 29 20 0a 2a 2a 20  x_notheld() .** 
256a0 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64  interface should
256b0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77   also return 1 w
256c0 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c  hen given a NULL
256d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74   pointer..*/.int
256e0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
256f0 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  eld(sqlite3_mute
25700 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  x*);.int sqlite3
25710 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73  _mutex_notheld(s
25720 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
25730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25740 20 4d 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a   Mutex Types.**.
25750 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
25760 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69  mutex_alloc()] i
25770 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73 20 61  nterface takes a
25780 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
25790 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65  .** which is one
257a0 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
257b0 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2f 0a  r constants..*/.
257c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
257d0 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20  UTEX_FAST       
257e0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
257f0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
25800 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a  URSIVE        1.
25810 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
25820 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
25830 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  ER    2.#define 
25840 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
25850 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20  TIC_MEM       3 
25860 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   /* sqlite3_mall
25870 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oc() */.#define 
25880 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
25890 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20  TIC_MEM2      4 
258a0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65   /* sqlite3_rele
258b0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a  ase_memory() */.
258c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
258d0 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
258e0 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69        5  /* sqli
258f0 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a  te3_random() */.
25900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
25910 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20  UTEX_STATIC_LRU 
25920 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20        6  /* lru 
25930 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a  page list */../*
25940 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
25950 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20  w-Level Control 
25960 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65  Of Database File
25970 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
25980 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
25990 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d  l()] interface m
259a0 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61  akes a direct ca
259b0 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69  ll to the.** xFi
259c0 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
259d0 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
259e0 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
259f0 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a  ject associated.
25a00 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ** with a partic
25a10 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64  ular database id
25a20 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
25a30 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
25a40 20 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66    The.** name of
25a50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
25a60 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
25a70 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ed to the databa
25a80 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20  se by the.** <a 
25a90 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63  href="lang_attac
25aa0 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f  h.html">ATTACH</
25ab0 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74  a> SQL command t
25ac0 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a  hat opened the.*
25ad0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 54 6f 20  * database.  To 
25ae0 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e  control the main
25af0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
25b00 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61  use the name "ma
25b10 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c  in".** or a NULL
25b20 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 74   pointer.  The t
25b30 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
25b40 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
25b50 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72  is routine.** ar
25b60 65 20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c  e passed directl
25b70 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  y through to the
25b80 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
25b90 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a  d parameters of.
25ba0 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** the xFileCont
25bb0 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 54 68 65  rol method.  The
25bc0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
25bd0 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
25be0 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f  l.** method beco
25bf0 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  mes the return v
25c00 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75  alue of this rou
25c10 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tine..**.** If t
25c20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
25c30 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f  ter (zDbName) do
25c40 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65  es not match the
25c50 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20   name of any.** 
25c60 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66 69  open database fi
25c70 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  le, then SQLITE_
25c80 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65  ERROR is returne
25c90 64 2e 20 20 54 68 69 73 20 65 72 72 6f 72 0a 2a  d.  This error.*
25ca0 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65  * code is not re
25cb0 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c  membered and wil
25cc0 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65  l not be recalle
25cd0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72  d by [sqlite3_er
25ce0 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b  rcode()].** or [
25cf0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
25d00 5d 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  ].  The underlyi
25d10 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ng xFileControl 
25d20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20  method might.** 
25d30 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49  also return SQLI
25d40 54 45 5f 45 52 52 4f 52 2e 20 20 54 68 65 72 65  TE_ERROR.  There
25d50 20 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69   is no way to di
25d60 73 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65  stinguish betwee
25d70 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63  n.** an incorrec
25d80 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e  t zDbName and an
25d90 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65   SQLITE_ERROR re
25da0 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e  turn from the un
25db0 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c  derlying.** xFil
25dc0 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e  eControl method.
25dd0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
25de0 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
25df0 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74  OCKSTATE].*/.int
25e00 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
25e10 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20  ntrol(sqlite3*, 
25e20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
25e30 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  ame, int op, voi
25e40 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f  d*);../*.** Undo
25e50 20 74 68 65 20 68 61 63 6b 20 74 68 61 74 20 63   the hack that c
25e60 6f 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 6e 67  onverts floating
25e70 20 70 6f 69 6e 74 20 74 79 70 65 73 20 74 6f 20   point types to 
25e80 69 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62  integer for.** b
25e90 75 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 73  uilds on process
25ea0 6f 72 73 20 77 69 74 68 6f 75 74 20 66 6c 6f 61  ors without floa
25eb0 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
25ec0 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  rt..*/.#ifdef SQ
25ed0 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
25ee0 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66  NG_POINT.# undef
25ef0 20 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a   double.#endif..
25f00 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
25f10 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20  us.}  /* End of 
25f20 74 68 65 20 27 65 78 74 65 72 6e 20 22 43 22 27  the 'extern "C"'
25f30 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66   block */.#endif
25f40 0a 23 65 6e 64 69 66 0a                          .#endif.