/ Hex Artifact Content
Login

Artifact 4ebbcb5a784493b6afb36fd83101e9c2e6d56707:


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 32 20 32 30 30 37 2f  in,v 1.262 2007/
05f0: 30 39 2f 32 31 20 30 34 3a 32 37 3a 30 33 20 64  09/21 04:27:03 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 73 74  ort due to const
2f60: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
2f70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2f80: 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30  E_MISMATCH    20
2f90: 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20     /* Data type 
2fa0: 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66  mismatch */.#def
2fb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ine SQLITE_MISUS
2fc0: 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c  E      21   /* L
2fd0: 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f  ibrary used inco
2fe0: 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69  rrectly */.#defi
2ff0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20  ne SQLITE_NOLFS 
3000: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73        22   /* Us
3010: 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e  es OS features n
3020: 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20  ot supported on 
3030: 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  host */.#define 
3040: 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20  SQLITE_AUTH     
3050: 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f     23   /* Autho
3060: 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20  rization denied 
3070: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3080: 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34  E_FORMAT      24
3090: 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20     /* Auxiliary 
30a0: 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20  database format 
30b0: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
30c0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
30d0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
30e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
30f0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
3100: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
3110: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
3120: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
3130: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
3140: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
3150: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
3160: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
3170: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
3180: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
3190: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
31a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31b0: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
31c0: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
31d0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
31e0: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
31f0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
3200: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
3210: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
3220: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
3230: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
3240: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
3250: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
3260: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
3270: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
3280: 2a 2a 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ** result codes 
3290: 64 65 73 63 72 69 62 65 64 20 61 74 20 72 65 73  described at res
32a0: 75 6c 74 2d 63 6f 64 65 73 2e 20 20 48 6f 77 65  ult-codes.  Howe
32b0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
32c0: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a  has shown that.*
32d0: 2a 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65 20  * many of these 
32e0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
32f0: 20 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61 69   too course-grai
3300: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
3310: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
3320: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
3330: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
3340: 61 73 20 75 73 65 72 73 20 6d 69 67 68 74 20 6c  as users might l
3350: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
3360: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
3370: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
3380: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
3390: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
33a0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
33b0: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
33c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
33d0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
33e0: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
33f0: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
3400: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
3410: 20 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72    The extended r
3420: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
3430: 65 6e 61 62 6c 65 64 20 28 6f 72 20 64 69 73 61  enabled (or disa
3440: 62 6c 65 64 29 20 66 6f 72 20 0a 2a 2a 20 65 61  bled) for .** ea
3450: 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ch database.** c
3460: 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20  onnection using 
3470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  the [sqlite3_ext
3480: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
3490: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 20 0a 2a  es()] API..** .*
34a0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
34b0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
34c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
34d0: 65 20 6c 69 73 74 65 64 20 61 62 6f 76 65 2e 0a  e listed above..
34e0: 2a 2a 20 57 65 20 65 78 70 65 63 74 20 74 68 65  ** We expect the
34f0: 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e   number of exten
3500: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
3510: 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a   will be expand.
3520: 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53  ** over time.  S
3530: 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65  oftware that use
3540: 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  s extended resul
3550: 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65  t codes should e
3560: 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20  xpect.** to see 
3570: 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73  new result codes
3580: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
3590: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
35a0: 2a 20 0a 2a 2a 20 54 68 65 20 73 79 6d 62 6f 6c  * .** The symbol
35b0: 69 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65  ic name for an e
35c0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
35d0: 6f 64 65 20 61 6c 77 61 79 73 20 63 6f 6e 74 61  ode always conta
35e0: 69 6e 73 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a  ins a related.**
35f0: 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20   primary result 
3600: 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78  code as a prefix
3610: 2e 20 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c  .  Primary resul
3620: 74 20 63 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20  t codes contain 
3630: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 22 5f 22 20  a single.** "_" 
3640: 63 68 61 72 61 63 74 65 72 2e 20 20 45 78 74 65  character.  Exte
3650: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3660: 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72  s contain two or
3670: 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63   more "_" charac
3680: 74 65 72 73 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d  ters..** The num
3690: 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e  eric value of an
36a0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
36b0: 20 63 6f 64 65 20 63 61 6e 20 62 65 20 63 6f 6e   code can be con
36c0: 76 65 72 74 65 64 20 74 6f 20 69 74 73 0a 2a 2a  verted to its.**
36d0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70   corresponding p
36e0: 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f  rimary result co
36f0: 64 65 20 62 79 20 6d 61 73 6b 69 6e 67 20 6f 66  de by masking of
3700: 66 20 74 68 65 20 6c 6f 77 65 72 20 38 20 62 79  f the lower 8 by
3710: 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  tes..**.** The S
3720: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
3730: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
3740: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
3750: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
3760: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
3770: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
3780: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
3790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
37a0: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OERR | (1<<8)).#
37b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
37c0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20  ERR_SHORT_READ  
37d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
37e0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
37f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
3800: 52 49 54 45 20 20 20 20 20 20 20 20 20 28 53 51  RITE         (SQ
3810: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
3820: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3830: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
3840: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
3850: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
3860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3870: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
3880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
3890: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
38a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
38b0: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 28 53  TRUNCATE      (S
38c0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
38d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
38e0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
38f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
3900: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
3910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3920: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
3930: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3940: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
3950: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3960: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 28  _RDLOCK        (
3970: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3980: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
3990: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
39a0: 54 45 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  TE        (SQLIT
39b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
39c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
39d0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
39e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
39f0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 0a  ERR | (11<<8))..
3a00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3a10: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
3a20: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
3a30: 2a 0a 2a 2a 20 43 6f 6d 62 69 6e 61 74 69 6f 6e  *.** Combination
3a40: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
3a50: 67 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  g bit values are
3a60: 20 75 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20   used as the.** 
3a70: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
3a80: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
3a90: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
3aa0: 61 63 65 20 61 6e 64 0a 2a 2a 20 61 73 20 66 6f  ace and.** as fo
3ab0: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
3ac0: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
3ad0: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
3ae0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
3af0: 2e 0a 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ..**.*/.#define 
3b00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
3b10: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
3b20: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
3b30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
3b40: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
3b50: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
3b60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
3b70: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
3b80: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
3b90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
3ba0: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
3bb0: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
3bc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
3bd0: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
3be0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
3bf0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
3c00: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
3c10: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
3c20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
3c30: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
3c40: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
3c50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
3c60: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
3c70: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
3c80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
3c90: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
3ca0: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
3cb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
3cc0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
3cd0: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
3ce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
3cf0: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
3d00: 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20  0002000.#define 
3d10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
3d20: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
3d30: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0004000../*.** C
3d40: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
3d50: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
3d60: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
3d70: 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65  eCapabilities me
3d80: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
3d90: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
3da0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
3db0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
3dc0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
3dd0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
3de0: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
3df0: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
3e00: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
3e10: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
3e20: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
3e30: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
3e40: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
3e50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
3e60: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
3e70: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
3e80: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
3e90: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
3ea0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
3eb0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
3ec0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
3ed0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
3ee0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
3ef0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
3f00: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
3f10: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
3f20: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
3f30: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
3f40: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
3f50: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
3f60: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
3f70: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
3f80: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
3f90: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
3fa0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
3fb0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
3fc0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
3fd0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
3fe0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
3ff0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
4000: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
4010: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
4020: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
4030: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
4040: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
4050: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
4060: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
4070: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
4080: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
4090: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
40a0: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66  Write()..*/.#def
40b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
40c0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
40d0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
40e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
40f0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
4100: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
4110: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4120: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
4130: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
4140: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4150: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
4160: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
4170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4180: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
4190: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
41a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
41b0: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
41c0: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
41d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
41e0: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
41f0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
4200: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4210: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
4220: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
4230: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4240: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
4250: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
4260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4270: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
4280: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
4290: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
42a0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
42b0: 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a   0x00000400../*.
42c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
42d0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
42e0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
42f0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  es one of the fo
4300: 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
4310: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
4320: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
4330: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
4340: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
4350: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
4360: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
4370: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
4380: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
4390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
43a0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
43b0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
43c0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
43d0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
43e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
43f0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
4400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4410: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
4420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4430: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
4440: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
4450: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
4460: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
4470: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
4480: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
4490: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
44a0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
44b0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
44c0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
44d0: 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  bination of the 
44e0: 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
44f0: 72 20 76 61 6c 75 65 73 20 61 73 0a 2a 2a 20 74  r values as.** t
4500: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
4510: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
4520: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
4530: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
4540: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
4550: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
4560: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
4570: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
4580: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
4590: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
45a0: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
45b0: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 20  ot be flushed.  
45c0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
45d0: 4e 4f 52 4d 41 4c 20 6d 65 61 6e 73 20 0a 2a 2a  NORMAL means .**
45e0: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
45f0: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
4600: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  .  The SQLITE_SY
4610: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61  NC_FULL flag mea
4620: 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ns .** to use Ma
4630: 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c  c OS-X style ful
4640: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
4650: 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65   fsync()..*/.#de
4660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
4670: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
4680: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
4690: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
46a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
46b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46c0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
46d0: 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a     0x00010.../*.
46e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
46f0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
4700: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
4710: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
4720: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
4730: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
4740: 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69  e in the OS.** i
4750: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20  nterface layer. 
4760: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
4770: 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65  nterface impleme
4780: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
4790: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
47a0: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
47b0: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
47c0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
47d0: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
47e0: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
47f0: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
4800: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
4810: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
4820: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
4830: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
4840: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
4850: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
4860: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
4870: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
4880: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
4890: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
48a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
48b0: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
48c0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
48d0: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
48e0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
48f0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
4900: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
4910: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
4920: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
4930: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
4940: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
4950: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
4960: 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e  lite3_vfs] xOpen
4970: 20 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73   method contains
4980: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
4990: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
49a0: 74 68 65 20 74 68 69 73 20 6f 62 6a 65 63 74 2e  the this object.
49b0: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65    This object de
49c0: 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74  fines the.** met
49d0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
49e0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
49f0: 72 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20  rations against 
4a00: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
4a10: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
4a20: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
4a30: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
4a40: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
4a50: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
4a60: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
4a70: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
4a80: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
4a90: 79 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65  ync()..*  The se
4aa0: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
4ab0: 6e 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20  n.** OS-X style 
4ac0: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53  fullsync.  The S
4ad0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20  QLITE_SYNC_DATA 
4ae0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
4af0: 20 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61   in to.** indica
4b00: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
4b10: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
4b20: 65 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  e and not its in
4b30: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a  ode needs to be.
4b40: 2a 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a  ** synced..** .*
4b50: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
4b60: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
4b70: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
4b80: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
4b90: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
4ba0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
4bb0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
4bc0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
4bd0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
4be0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
4bf0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
4c00: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
4c10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
4c20: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
4c30: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
4c40: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
4c50: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
4c60: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
4c70: 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68  ck.  .** The xCh
4c80: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
4c90: 29 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a  ) method looks.*
4ca0: 2a 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20  * to see if any 
4cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4cc0: 69 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74  ion, either in t
4cd0: 68 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f  his.** process o
4ce0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
4cf0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
4d00: 69 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c  ing an RESERVED,
4d10: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
4d20: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
4d30: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
4d40: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
4d50: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
4d60: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
4d70: 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54  if not..** .** T
4d80: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
4d90: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
4da0: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
4db0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
4dc0: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
4dd0: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
4de0: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
4df0: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
4e00: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e10: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
4e20: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
4e30: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
4e40: 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69  ument.** is an i
4e50: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
4e60: 20 54 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   The third.** ar
4e70: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
4e80: 72 69 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63  ric pointer whic
4e90: 68 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  h is intended to
4ea0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   be a pointer.**
4eb0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
4ec0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
4ed0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
4ee0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
4ef0: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
4f00: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
4f10: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
4f20: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
4f30: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
4f40: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
4f50: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
4f60: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
4f70: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
4f80: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
4f90: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
4fa0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
4fb0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
4fc0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
4fd0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
4fe0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
4ff0: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
5000: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
5010: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
5020: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
5030: 6e 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51  n use. .** A [SQ
5040: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
5050: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
5060: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
5070: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
5080: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
5090: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
50a0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
50b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
50c0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20  uld use opcodes 
50d0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
50e0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
50f0: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
5100: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
5110: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
5120: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
5130: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
5140: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
5150: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
5160: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
5170: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
5180: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
5190: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
51a0: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
51b0: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
51c0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
51d0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
51e0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
51f0: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
5200: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
5210: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
5220: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
5230: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
5240: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
5250: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
5260: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5270: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
5280: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5290: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
52a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
52b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
52c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
52d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
52e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
52f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
5300: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5310: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
5320: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5330: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
5340: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5350: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
5360: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
5370: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
5380: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
5390: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
53a0: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
53b0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
53c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
53d0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
53e0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
53f0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
5400: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
5410: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5420: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
5430: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
5440: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
5450: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
5460: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
5470: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
5480: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
5490: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
54a0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
54b0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
54c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
54d0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
54e0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
54f0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
5500: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
5510: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
5520: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
5530: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
5540: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
5550: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
5560: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
5570: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5580: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
5590: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
55a0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
55b0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
55c0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
55d0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
55e0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
55f0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
5600: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
5610: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
5620: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
5630: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5640: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
5650: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
5660: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
5670: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
5680: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
5690: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
56a0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
56b0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
56c0: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
56d0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
56e0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
56f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
5700: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
5710: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
5720: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
5730: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
5740: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
5750: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
5760: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
5770: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
5780: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
5790: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
57a0: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
57b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
57c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
57d0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
57e0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
57f0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
5800: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
5810: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  e*);.  int (*xFi
5820: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
5830: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
5840: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
5850: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
5860: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
5870: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
5880: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
5890: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
58a0: 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f  *);.  /* Additio
58b0: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
58c0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
58d0: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
58e0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
58f0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
5900: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
5910: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
5920: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
5930: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
5940: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
5950: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
5960: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5970: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
5980: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5990: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
59a0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
59b0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
59c0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
59d0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
59e0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
59f0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
5a00: 63 61 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  cases the xFileC
5a10: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
5a20: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
5a30: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
5a40: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
5a50: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
5a60: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
5a70: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
5a80: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
5a90: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
5aa0: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
5ab0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5ac0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
5ad0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
5ae0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
5af0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 20 54 68  t points to.  Th
5b00: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
5b10: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
5b20: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
5b30: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
5b40: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
5b50: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
5b60: 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  fined..*/.#defin
5b70: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
5b80: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
5b90: 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
5ba0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
5bb0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
5bc0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
5bd0: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
5be0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
5bf0: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
5c00: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
5c10: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
5c20: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
5c30: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
5c40: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
5c50: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
5c60: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
5c70: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
5c80: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
5c90: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5ca0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
5cb0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
5cc0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
5cd0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
5ce0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
5cf0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
5d00: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
5d10: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
5d20: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
5d30: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
5d40: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
5d50: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
5d60: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
5d70: 61 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a  ace between the.
5d80: 2a 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  ** SQLite core a
5d90: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
5da0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
5db0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
5dc0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
5dd0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
5de0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
5df0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a  file system"..**
5e00: 0a 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e  .** The iVersion
5e10: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
5e20: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
5e30: 20 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74 75   larger for futu
5e40: 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
5e50: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
5e60: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
5e70: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
5e80: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
5e90: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
5ea0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
5eb0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
5ec0: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
5ed0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
5ee0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
5ef0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
5f00: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
5f10: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
5f20: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
5f30: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
5f40: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
5f50: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
5f60: 52 65 67 69 73 74 65 72 65 64 20 76 66 73 20 6d  Registered vfs m
5f70: 6f 64 75 6c 65 73 20 61 72 65 20 6b 65 70 74 20  odules are kept 
5f80: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
5f90: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
5fa0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
5fb0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
5fc0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
5fd0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
5fe0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
5ff0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
6000: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
6010: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
6020: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
6030: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
6040: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
6050: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 0a  rches the list..
6060: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
6070: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
6080: 79 20 66 69 65 6c 64 73 20 69 6e 20 74 68 65 20  y fields in the 
6090: 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20  sqlite3_vfs .** 
60a0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
60b0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
60c0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
60d0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
60e0: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
60f0: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
6100: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
6110: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
6120: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
6130: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
6140: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
6150: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
6160: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
6170: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
6180: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
6190: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
61a0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
61b0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
61c0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
61d0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
61e0: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
61f0: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
6200: 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  es..**.** SQLite
6210: 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20   will guarantee 
6220: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
6230: 6d 65 20 73 74 72 69 6e 67 20 70 61 73 73 65 64  me string passed
6240: 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20 69   to.** xOpen() i
6250: 73 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61 6d  s a full pathnam
6260: 65 20 61 73 20 67 65 6e 65 72 61 74 65 64 20 62  e as generated b
6270: 79 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  y xFullPathname(
6280: 29 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74 68  ) and.** that th
6290: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
62a0: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
62b0: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
62c0: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
62d0: 2e 20 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74  .  So the [sqlit
62e0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f  e3_file] can sto
62f0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
6300: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
6310: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
6320: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
6330: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
6340: 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ason..**.** The 
6350: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
6360: 6f 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20 63  o xOpen() is a c
6370: 6f 70 79 20 6f 66 20 74 68 65 20 66 6c 61 67 73  opy of the flags
6380: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
6390: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
63a0: 28 29 5d 2e 20 20 49 66 20 5b 73 71 6c 69 74 65  ()].  If [sqlite
63b0: 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71  3_open()] or [sq
63c0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 0a  lite3_open16()].
63d0: 2a 2a 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ** is used, then
63e0: 20 66 6c 61 67 73 20 69 73 20 5b 53 51 4c 49 54   flags is [SQLIT
63f0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
6400: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
6410: 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 20 49 66 20  _CREATE]..** If 
6420: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
6430: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
6440: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
6450: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
6460: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
6470: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
6480: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
6490: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a  tFlags may be.**
64a0: 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c   set..** .** SQL
64b0: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
64c0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
64d0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
64e0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
64f0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
6500: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
6510: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a 2a  ng opened:.** .*
6520: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
6530: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
6540: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
6550: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
6560: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
6570: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
6580: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
6590: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
65a0: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
65b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
65c0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
65d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
65e0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
65f0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
6600: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
6610: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  JOURNAL].** </ul
6620: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  >.**.** The file
6630: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
6640: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
6650: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
6660: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20  s to.** changes 
6670: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
6680: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
6690: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
66a0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
66b0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
66c0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
66d0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
66e0: 2c 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  , might make.** 
66f0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
6700: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
6710: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
6720: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72 65 0a  his journal are.
6730: 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e  ** also a no-op.
6740: 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f    Any attempt to
6750: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
6760: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
6770: 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 68 65  IOERR..** Or the
6780: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
6790: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
67a0: 74 68 65 20 61 20 64 61 74 61 62 61 73 65 20 66  the a database f
67b0: 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 64  ile will.** be d
67c0: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
67d0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
67e0: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
67f0: 61 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20 61  andom order.** a
6800: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
6810: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
6820: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20  rdingly..** .** 
6830: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
6840: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
6850: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
6860: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a   to the xOpen.**
6870: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20   method:.** .** 
6880: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
6890: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
68a0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
68b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
68c0: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
68d0: 3e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 5b 53 51  >.** .** The [SQ
68e0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
68f0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
6900: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
6910: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
6920: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
6930: 73 65 64 2e 20 20 54 68 69 73 20 77 69 6c 6c 20  sed.  This will 
6940: 61 6c 77 61 79 73 20 62 65 20 73 65 74 20 66 6f  always be set fo
6950: 72 20 54 45 4d 50 20 0a 2a 2a 20 64 61 74 61 62  r TEMP .** datab
6960: 61 73 65 73 20 61 6e 64 20 6a 6f 75 72 6e 61 6c  ases and journal
6970: 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75  s and for subjou
6980: 72 6e 61 6c 73 2e 20 20 54 68 65 20 0a 2a 2a 20  rnals.  The .** 
6990: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
69a0: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61  LUSIVE] flag mea
69b0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
69c0: 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20  ld be opened.** 
69d0: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
69e0: 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67  cess.  This flag
69f0: 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20   is set for all 
6a00: 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20  files except.** 
6a10: 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74  for the main dat
6a20: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 0a  abase file..** .
6a30: 2a 2a 20 53 70 61 63 65 20 74 6f 20 68 6f 6c 64  ** Space to hold
6a40: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
6a50: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
6a60: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
6a70: 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rd .** argument 
6a80: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 6c 6c 6f  to xOpen is allo
6a90: 63 61 74 65 64 20 62 79 20 63 61 6c 6c 65 72 20  cated by caller 
6aa0: 28 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65  (the SQLite core
6ab0: 29 2e 20 0a 2a 2a 20 73 7a 4f 73 46 69 6c 65 20  ). .** szOsFile 
6ac0: 62 79 74 65 73 20 61 72 65 20 61 6c 6c 6f 63 61  bytes are alloca
6ad0: 74 65 64 20 66 6f 72 20 74 68 69 73 20 6f 62 6a  ted for this obj
6ae0: 65 63 74 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  ect.  The xOpen 
6af0: 6d 65 74 68 6f 64 0a 2a 2a 20 66 69 6c 6c 73 20  method.** fills 
6b00: 69 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  in the allocated
6b10: 20 73 70 61 63 65 2e 0a 2a 2a 20 0a 2a 2a 20 54   space..** .** T
6b20: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
6b30: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
6b40: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
6b50: 43 45 53 53 5f 45 58 49 53 54 53 5d 20 0a 2a 2a  CESS_EXISTS] .**
6b60: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
6b70: 20 65 78 69 73 74 61 6e 63 65 20 6f 66 20 61 20   existance of a 
6b80: 66 69 6c 65 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  file,.** or [SQL
6b90: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
6ba0: 52 49 54 45 5d 20 74 6f 20 74 65 73 74 20 74 6f  RITE] to test to
6bb0: 20 73 65 65 0a 2a 2a 20 69 66 20 61 20 66 69 6c   see.** if a fil
6bc0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
6bd0: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
6be0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
6bf0: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 74  AD].** to test t
6c00: 6f 20 73 65 65 20 69 66 20 61 20 66 69 6c 65 20  o see if a file 
6c10: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
6c20: 61 62 6c 65 2e 20 20 54 68 65 20 66 69 6c 65 20  able.  The file 
6c30: 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69 72  can be a .** dir
6c40: 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 53  ectory..** .** S
6c50: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
6c60: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
6c70: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
6c80: 20 62 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68 65   byte for.** the
6c90: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 73 20   output buffers 
6ca0: 66 6f 72 20 78 47 65 74 54 65 6d 70 6e 61 6d 65  for xGetTempname
6cb0: 20 61 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61   and xFullPathna
6cc0: 6d 65 2e 20 54 68 65 20 65 78 61 63 74 0a 2a 2a  me. The exact.**
6cd0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
6ce0: 70 75 74 20 62 75 66 66 65 72 20 69 73 20 61 6c  put buffer is al
6cf0: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
6d00: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
6d10: 20 0a 2a 2a 20 6d 65 74 68 6f 64 73 2e 20 49 66   .** methods. If
6d20: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
6d30: 65 72 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  er is not large 
6d40: 65 6e 6f 75 67 68 2c 20 53 51 4c 49 54 45 5f 43  enough, SQLITE_C
6d50: 41 4e 54 4f 50 45 4e 0a 2a 2a 20 73 68 6f 75 6c  ANTOPEN.** shoul
6d60: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 41  d be returned. A
6d70: 73 20 74 68 69 73 20 69 73 20 68 61 6e 64 6c 65  s this is handle
6d80: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
6d90: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 0a 2a 2a  or by SQLite,.**
6da0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
6db0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
6dc0: 76 6f 75 72 20 74 6f 20 70 72 65 76 65 6e 74 20  vour to prevent 
6dd0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
6de0: 0a 2a 2a 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  .** mxPathname t
6df0: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
6e00: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
6e10: 20 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d   .** The xRandom
6e20: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
6e30: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
6e40: 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  me() interfaces.
6e50: 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  ** are not stric
6e60: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
6e70: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
6e80: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
6e90: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
6ea0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
6eb0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
6ec0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
6ed0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
6ee0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
6ef0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
6f00: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
6f10: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
6f20: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
6f30: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
6f40: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
6f50: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
6f60: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 20  mness obtained. 
6f70: 20 54 68 65 0a 2a 2a 20 78 53 6c 65 65 70 28 29   The.** xSleep()
6f80: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 20 74 68   method cause th
6f90: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
6fa0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
6fb0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
6fc0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
6fd0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65  onds given.  The
6fe0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
6ff0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
7000: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
7010: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
7020: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a  rrent date and.*
7030: 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64  * time..*/.typed
7040: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7050: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
7060: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7070: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
7080: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
7090: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
70a0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a  version number *
70b0: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
70c0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
70d0: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
70e0: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
70f0: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
7100: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
7110: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
7120: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
7130: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
7140: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
7150: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
7160: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
7170: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
7180: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
7190: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
71a0: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
71b0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
71c0: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
71d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
71e0: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
71f0: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
7200: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
7210: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
7220: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
7230: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
7240: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
7250: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
7260: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
7270: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
7280: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
7290: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
72a0: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
72b0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
72c0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
72d0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  ags);.  int (*xG
72e0: 65 74 54 65 6d 70 6e 61 6d 65 29 28 73 71 6c 69  etTempname)(sqli
72f0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 4f  te3_vfs*, int nO
7300: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
7310: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
7320: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
7330: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
7340: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
7350: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
7360: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
7370: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
7380: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
7390: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
73a0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
73b0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
73c0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
73d0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  sg);.  void *(*x
73e0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
73f0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
7400: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b   char *zSymbol);
7410: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
7420: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
7430: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
7440: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
7450: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
7460: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
7470: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
7480: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
7490: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
74a0: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
74b0: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
74c0: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
74d0: 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65  *);.  /* New fie
74e0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
74f0: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
7500: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
7510: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
7520: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
7530: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
7540: 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ppens. */.};../*
7550: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
7560: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
7570: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
7580: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
7590: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
75a0: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
75b0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
75c0: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
75d0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
75e0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
75f0: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
7600: 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 6b 69 6e 64  mine.** the kind
7610: 20 6f 66 20 77 68 61 74 20 6b 69 6e 64 20 6f 66   of what kind of
7620: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
7630: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
7640: 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f  is.** looking fo
7650: 72 2e 20 20 57 69 74 68 20 53 51 4c 49 54 45 5f  r.  With SQLITE_
7660: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
7670: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
7680: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
7690: 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65  ks to see if the
76a0: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 20 20 57   file exists.  W
76b0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
76c0: 53 5f 52 45 41 44 57 52 49 54 45 2c 0a 2a 2a 20  S_READWRITE,.** 
76d0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
76e0: 6f 64 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65  od checks to see
76f0: 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
7700: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 0a 2a 2a  both readable.**
7710: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 20 20   and writable.  
7720: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
7730: 53 53 5f 52 45 41 44 20 74 68 65 20 78 41 63 63  SS_READ the xAcc
7740: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
7750: 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74  ecks to see if t
7760: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
7770: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ble..*/.#define 
7780: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
7790: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
77a0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
77b0: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66  READWRITE 1.#def
77c0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
77d0: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f  S_READ      2../
77e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
77f0: 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
7800: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
7810: 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69   Codes.**.** Thi
7820: 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  s routine enable
7830: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
7840: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  e.** [SQLITE_IOE
7850: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
7860: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
7870: 20 66 65 61 74 75 72 65 2e 0a 2a 2a 20 42 79 20   feature..** By 
7880: 64 65 66 61 75 6c 74 2c 20 53 51 4c 69 74 65 20  default, SQLite 
7890: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
78a0: 75 72 6e 20 6f 6e 65 20 6f 66 20 6f 6e 6c 79 20  urn one of only 
78b0: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
78c0: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
78d0: 74 20 63 6f 64 65 73 5d 2e 20 20 57 68 65 6e 20  t codes].  When 
78e0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
78f0: 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  codes.** are ena
7900: 62 6c 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  bled by this rou
7910: 74 69 6e 65 2c 20 74 68 65 20 72 65 70 65 74 6f  tine, the repeto
7920: 69 72 65 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ire of result co
7930: 64 65 73 20 63 61 6e 20 62 65 0a 2a 2a 20 6d 75  des can be.** mu
7940: 63 68 20 6c 61 72 67 65 72 20 61 6e 64 20 63 61  ch larger and ca
7950: 6e 20 28 68 6f 70 65 66 75 6c 6c 79 29 20 70 72  n (hopefully) pr
7960: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
7970: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
7980: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 63 61 75  ** about the cau
7990: 73 65 20 6f 66 20 61 6e 20 65 72 72 6f 72 2e 0a  se of an error..
79a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
79b0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 62   argument is a b
79c0: 6f 6f 6c 65 61 6e 20 76 61 6c 75 65 20 74 68 61  oolean value tha
79d0: 74 20 74 75 72 6e 73 20 65 78 74 65 6e 64 65 64  t turns extended
79e0: 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
79f0: 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 20 20 45 78   on and off.  Ex
7a00: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
7a10: 64 65 73 20 61 72 65 20 6f 66 66 20 62 79 20 64  des are off by d
7a20: 65 66 61 75 6c 74 20 66 6f 72 0a 2a 2a 20 62 61  efault for.** ba
7a30: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
7a40: 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
7a50: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
7a60: 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
7a70: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
7a80: 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
7a90: 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
7aa0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7ab0: 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
7ac0: 69 64 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e  id.**.** Each en
7ad0: 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
7ae0: 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
7af0: 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
7b00: 64 20 69 6e 74 65 67 65 72 20 6b 65 79 0a 2a 2a  d integer key.**
7b10: 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77   called the "row
7b20: 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69  id". The rowid i
7b30: 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
7b40: 6c 65 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  le as an undecla
7b50: 72 65 64 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 61  red.** column na
7b60: 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
7b70: 6f 72 20 5f 52 4f 57 49 44 5f 2e 20 20 49 66 20  or _ROWID_.  If 
7b80: 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
7b90: 63 6f 6c 75 6d 6e 20 6f 66 0a 2a 2a 20 74 79 70  column of.** typ
7ba0: 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52  e INTEGER PRIMAR
7bb0: 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20  Y KEY then that 
7bc0: 63 6f 6c 75 6d 6e 20 69 73 20 61 6e 6f 74 68 65  column is anothe
7bd0: 72 20 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74  r an alias for t
7be0: 68 65 0a 2a 2a 20 72 6f 77 69 64 2e 0a 2a 2a 0a  he.** rowid..**.
7bf0: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
7c00: 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69  returns the rowi
7c10: 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  d of the most re
7c20: 63 65 6e 74 20 49 4e 53 45 52 54 20 69 6e 74 6f  cent INSERT into
7c30: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
7c40: 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61   from the databa
7c50: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 67 69  se connection gi
7c60: 76 65 6e 20 69 6e 20 74 68 65 20 66 69 72 73 74  ven in the first
7c70: 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20   .** argument.  
7c80: 49 66 20 6e 6f 20 69 6e 73 65 72 74 73 20 68 61  If no inserts ha
7c90: 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
7ca0: 20 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61 73   on this databas
7cb0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  e.** connection,
7cc0: 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
7cd0: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49  d..**.** If an I
7ce0: 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 74  NSERT occurs wit
7cf0: 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74  hin a trigger, t
7d00: 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66  hen the rowid of
7d10: 20 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64   the.** inserted
7d20: 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64   row is returned
7d30: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
7d40: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
7d50: 74 72 69 67 67 65 72 0a 2a 2a 20 69 73 20 72 75  trigger.** is ru
7d60: 6e 6e 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65  nning.  But once
7d70: 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72   the trigger ter
7d80: 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c  minates, the val
7d90: 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
7da0: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
7db0: 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61  everts to the la
7dc0: 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65  st value inserte
7dd0: 64 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20  d before the.** 
7de0: 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a  trigger fired..*
7df0: 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
7e00: 74 68 72 65 61 64 20 64 6f 65 73 20 61 20 6e 65  thread does a ne
7e10: 77 20 69 6e 73 65 72 74 20 6f 6e 20 74 68 65 20  w insert on the 
7e20: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
7e30: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
7e40: 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
7e50: 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
7e60: 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
7e70: 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
7e80: 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
7e90: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
7ea0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
7eb0: 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 73 71 6c 69  defined..*/.sqli
7ec0: 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
7ed0: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
7ee0: 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
7ef0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7f00: 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
7f10: 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
7f20: 64 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  d.**.** This fun
7f30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
7f40: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
7f50: 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
7f60: 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 28  ere changed.** (
7f70: 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
7f80: 65 6c 65 74 65 64 29 20 62 79 20 74 68 65 20 6d  eleted) by the m
7f90: 6f 73 74 20 72 65 63 65 6e 74 20 53 51 4c 20 73  ost recent SQL s
7fa0: 74 61 74 65 6d 65 6e 74 2e 20 20 4f 6e 6c 79 0a  tatement.  Only.
7fb0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ** changes that 
7fc0: 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
7fd0: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49 4e  cified by the IN
7fe0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
7ff0: 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
8000: 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
8010: 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
8020: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
8030: 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e  * triggers are n
8040: 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 55 73 65  ot counted.  Use
8050: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
8060: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
8070: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69  unction.** to fi
8080: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
8090: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
80a0: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
80b0: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
80c0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 57 69 74 68 69  ers..**.** Withi
80d0: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
80e0: 74 72 69 67 67 65 72 2c 20 74 68 65 20 73 71 6c  trigger, the sql
80f0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
8100: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 0a  nterface can be.
8110: 2a 2a 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  ** called to fin
8120: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
8130: 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
8140: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
8150: 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
8160: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
8170: 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
8180: 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
8190: 20 6f 66 20 74 68 65 20 74 72 69 67 67 65 72 2e   of the trigger.
81a0: 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 63 68 61 6e 67  .**.** All chang
81b0: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2c 20  es are counted, 
81c0: 65 76 65 6e 20 69 66 20 74 68 65 79 20 77 65 72  even if they wer
81d0: 65 20 6c 61 74 65 72 20 75 6e 64 6f 6e 65 20 62  e later undone b
81e0: 79 20 61 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b 20  y a.** ROLLBACK 
81f0: 6f 72 20 41 42 4f 52 54 2e 20 20 45 78 63 65 70  or ABORT.  Excep
8200: 74 2c 20 63 68 61 6e 67 65 73 20 61 73 73 6f 63  t, changes assoc
8210: 69 61 74 65 64 20 77 69 74 68 20 63 72 65 61 74  iated with creat
8220: 69 6e 67 20 61 6e 64 0a 2a 2a 20 64 72 6f 70 70  ing and.** dropp
8230: 69 6e 67 20 74 61 62 6c 65 73 20 61 72 65 20 6e  ing tables are n
8240: 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  ot counted..**.*
8250: 2a 20 49 66 20 61 20 63 61 6c 6c 62 61 63 6b 20  * If a callback 
8260: 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33  invokes [sqlite3
8270: 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
8280: 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
8290: 75 72 73 69 76 65 6c 79 2c 0a 2a 2a 20 74 68 65  ursively,.** the
82a0: 6e 20 74 68 65 20 63 68 61 6e 67 65 73 20 69 6e  n the changes in
82b0: 20 74 68 65 20 69 6e 6e 65 72 2c 20 72 65 63 75   the inner, recu
82c0: 72 73 69 76 65 20 63 61 6c 6c 20 61 72 65 20 63  rsive call are c
82d0: 6f 75 6e 74 65 64 20 74 6f 67 65 74 68 65 72 0a  ounted together.
82e0: 2a 2a 20 77 69 74 68 20 74 68 65 20 63 68 61 6e  ** with the chan
82f0: 67 65 73 20 69 6e 20 74 68 65 20 6f 75 74 65 72  ges in the outer
8300: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   call..**.** SQL
8310: 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
8320: 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45  he command "DELE
8330: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
8340: 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63  ithout a WHERE c
8350: 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70  lause.** by drop
8360: 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74  ping and recreat
8370: 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20  ing the table.  
8380: 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61  (This is much fa
8390: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a  ster than going.
83a0: 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64  ** through and d
83b0: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75  eleting individu
83c0: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d  al elements from
83d0: 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65   the table.)  Be
83e0: 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73  cause of.** this
83f0: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74   optimization, t
8400: 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20  he change count 
8410: 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  for "DELETE FROM
8420: 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a   table" will be.
8430: 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65  ** zero regardle
8440: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
8450: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
8460: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
8470: 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c  y in the.** tabl
8480: 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63  e. To get an acc
8490: 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74  urate count of t
84a0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
84b0: 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a  s deleted, use.*
84c0: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  * "DELETE FROM t
84d0: 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e  able WHERE 1" in
84e0: 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  stead..**.** If 
84f0: 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d  another thread m
8500: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
8510: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
8520: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
8530: 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
8540: 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ne is running th
8550: 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
8560: 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74  lue of this rout
8570: 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ine.** is undefi
8580: 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
8590: 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
85a0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
85b0: 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
85c0: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
85d0: 69 66 69 65 64 0a 2a 2a 2a 0a 2a 2a 20 54 68 69  ified.***.** Thi
85e0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
85f0: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
8600: 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
8610: 68 61 74 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a  hat have been.**
8620: 20 6d 6f 64 69 66 69 65 64 20 62 79 20 49 4e 53   modified by INS
8630: 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
8640: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73  ELETE statements
8650: 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
8660: 61 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61  ase handle.** wa
8670: 73 20 6f 70 65 6e 65 64 2e 20 54 68 69 73 20 69  s opened. This i
8680: 6e 63 6c 75 64 65 73 20 55 50 44 41 54 45 2c 20  ncludes UPDATE, 
8690: 49 4e 53 45 52 54 20 61 6e 64 20 44 45 4c 45 54  INSERT and DELET
86a0: 45 20 73 74 61 74 65 6d 65 6e 74 73 20 65 78 65  E statements exe
86b0: 63 75 74 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  cuted.** as part
86c0: 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
86d0: 72 61 6d 73 2e 20 41 6c 6c 20 63 68 61 6e 67 65  rams. All change
86e0: 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73  s are counted as
86f0: 20 73 6f 6f 6e 20 61 73 20 74 68 65 0a 2a 2a 20   soon as the.** 
8700: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
8710: 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
8720: 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
8730: 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
8740: 65 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  e is.** passed t
8750: 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
8760: 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
8770: 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
8780: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
8790: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
87a0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
87b0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
87c0: 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
87d0: 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
87e0: 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
87f0: 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
8800: 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
8810: 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
8820: 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73  table.  (This is
8830: 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61   much faster tha
8840: 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
8850: 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
8860: 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
8870: 6e 74 73 20 66 6f 72 6d 20 74 68 65 20 74 61 62  nts form the tab
8880: 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66  le.)  Because of
8890: 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a  .** this optimiz
88a0: 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67  ation, the chang
88b0: 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c  e count for "DEL
88c0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
88d0: 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20  will be.** zero 
88e0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
88f0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d  e number of elem
8900: 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f  ents that were o
8910: 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65  riginally in the
8920: 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65  .** table. To ge
8930: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
8940: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
8950: 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
8960: 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
8970: 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
8980: 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a  RE 1" instead..*
8990: 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
89a0: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
89b0: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
89c0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
89d0: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68  tion.** while th
89e0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
89f0: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 72  nning then the r
8a00: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
8a10: 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69  his routine.** i
8a20: 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
8a30: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
8a40: 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
8a50: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
8a60: 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
8a70: 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
8a80: 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  uery.**.** This 
8a90: 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
8aa0: 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
8ab0: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
8ac0: 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
8ad0: 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
8ae0: 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
8af0: 79 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  y.  This routine
8b00: 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
8b10: 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
8b20: 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
8b30: 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
8b40: 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
8b50: 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
8b60: 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
8b70: 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
8b80: 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
8b90: 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
8ba0: 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65  **.** It is safe
8bb0: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
8bc0: 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
8bd0: 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
8be0: 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
8bf0: 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
8c00: 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
8c10: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
8c20: 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
8c30: 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
8c40: 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
8c50: 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 63  ith a database c
8c60: 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a  onnection that.*
8c70: 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
8c80: 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
8c90: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
8ca0: 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
8cb0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 20 6f 70 65  *.** The SQL ope
8cc0: 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
8cd0: 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
8ce0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
8cf0: 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66  NTERRUPT]..** If
8d00: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 65 64 20   an interrupted 
8d10: 6f 70 65 72 61 74 69 6f 6e 20 77 61 73 20 61 6e  operation was an
8d20: 20 75 70 64 61 74 65 20 74 68 61 74 20 69 73 20   update that is 
8d30: 69 6e 73 69 64 65 20 61 6e 0a 2a 2a 20 65 78 70  inside an.** exp
8d40: 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
8d50: 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
8d60: 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  re transaction w
8d70: 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 0a 2a 2a  ill be rolled.**
8d80: 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
8d90: 6c 6c 79 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  lly..*/.void sql
8da0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
8db0: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
8dc0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
8dd0: 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
8de0: 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
8df0: 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
8e00: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
8e10: 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 67 69  n true if the gi
8e20: 76 65 6e 20 69 6e 70 75 74 20 73 74 72 69 6e 67  ven input string
8e30: 20 63 6f 6d 70 72 69 73 65 73 0a 2a 2a 20 6f 6e   comprises.** on
8e40: 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65  e or more comple
8e50: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
8e60: 73 2e 20 46 6f 72 20 74 68 65 20 73 71 6c 69 74  s. For the sqlit
8e70: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 63 61  e3_complete() ca
8e80: 6c 6c 2c 0a 2a 2a 20 74 68 65 20 70 61 72 61 6d  ll,.** the param
8e90: 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 6e  eter must be a n
8ea0: 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ul-terminated UT
8eb0: 46 2d 38 20 73 74 72 69 6e 67 2e 20 46 6f 72 0a  F-8 string. For.
8ec0: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ** sqlite3_compl
8ed0: 65 74 65 31 36 28 29 2c 20 61 20 6e 75 6c 2d 74  ete16(), a nul-t
8ee0: 65 72 6d 69 6e 61 74 65 64 20 6d 61 63 68 69 6e  erminated machin
8ef0: 65 20 62 79 74 65 20 6f 72 64 65 72 20 55 54 46  e byte order UTF
8f00: 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 73  -16 string.** is
8f10: 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
8f20: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
8f30: 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
8f40: 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
8f50: 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
8f60: 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
8f70: 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
8f80: 66 6f 72 6d 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  forms one or mor
8f90: 65 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  e complete SQL s
8fa0: 74 61 74 65 6d 65 6e 74 73 20 6f 72 0a 2a 2a 20  tatements or.** 
8fb0: 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
8fc0: 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
8fd0: 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
8fe0: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 74 6f   statements into
8ff0: 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
9000: 61 72 73 69 6e 67 2e 20 54 68 65 20 61 6c 67 6f  arsing. The algo
9010: 72 69 74 68 6d 20 69 73 20 73 69 6d 70 6c 65 2e  rithm is simple.
9020: 20 20 49 66 20 74 68 65 20 0a 2a 2a 20 6c 61 73    If the .** las
9030: 74 20 74 6f 6b 65 6e 20 6f 74 68 65 72 20 74 68  t token other th
9040: 61 6e 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f  an spaces and co
9050: 6d 6d 65 6e 74 73 20 69 73 20 61 20 73 65 6d 69  mments is a semi
9060: 63 6f 6c 6f 6e 2c 20 74 68 65 6e 20 72 65 74 75  colon, then retu
9070: 72 6e 20 0a 2a 2a 20 74 72 75 65 2e 20 20 41 63  rn .** true.  Ac
9080: 74 75 61 6c 6c 79 2c 20 74 68 65 20 61 6c 67 6f  tually, the algo
9090: 72 69 74 68 6d 20 69 73 20 61 20 6c 69 74 74 6c  rithm is a littl
90a0: 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74  e more complicat
90b0: 65 64 20 74 68 61 6e 20 74 68 61 74 0a 2a 2a 20  ed than that.** 
90c0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 61 6c  in order to deal
90d0: 20 77 69 74 68 20 74 72 69 67 67 65 72 73 2c 20   with triggers, 
90e0: 62 75 74 20 74 68 65 20 62 61 73 69 63 20 69 64  but the basic id
90f0: 65 61 20 69 73 20 74 68 65 20 73 61 6d 65 3a 20  ea is the same: 
9100: 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
9110: 74 20 69 73 20 6e 6f 74 20 63 6f 6d 70 6c 65 74  t is not complet
9120: 65 20 75 6e 6c 65 73 73 20 69 74 20 65 6e 64 73  e unless it ends
9130: 20 69 6e 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2e   in a semicolon.
9140: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
9150: 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
9160: 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
9170: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
9180: 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
9190: 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
91a0: 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
91b0: 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
91c0: 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
91d0: 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rrors.**.** This
91e0: 20 72 6f 75 74 69 6e 65 20 69 64 65 6e 74 69 66   routine identif
91f0: 69 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ies a callback f
9200: 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67  unction that mig
9210: 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ht be invoked.**
9220: 20 77 68 65 6e 65 76 65 72 20 61 6e 20 61 74 74   whenever an att
9230: 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
9240: 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  open a database 
9250: 74 61 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61  table .** that a
9260: 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6f 72  nother thread or
9270: 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
9280: 6b 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62  ked..** If the b
9290: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
92a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
92b0: 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 28 6f 72 20  TE_BUSY].** (or 
92c0: 73 6f 6d 65 74 69 6d 65 73 20 5b 53 51 4c 49 54  sometimes [SQLIT
92d0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
92e0: 29 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ).** is returned
92f0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
9300: 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
9310: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74  he lock..** If t
9320: 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
9330: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
9340: 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61  en the.** callba
9350: 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  ck will be invok
9360: 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
9370: 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66  ments.  The.** f
9380: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
9390: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20   the handler is 
93a0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
93b0: 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
93c0: 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
93d0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
93e0: 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 65  is routine.  The
93f0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
9400: 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c   to.** the handl
9410: 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  er is the number
9420: 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
9430: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
9440: 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
9450: 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
9460: 6b 69 6e 67 20 65 76 65 6e 74 2e 20 49 66 20 74  king event. If t
9470: 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
9480: 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
9490: 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
94a0: 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
94b0: 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
94c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
94d0: 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
94e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
94f0: 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
9500: 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  urned..** If the
9510: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
9520: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
9530: 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
9540: 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
9550: 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
9560: 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
9570: 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
9580: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
9590: 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
95a0: 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
95b0: 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
95c0: 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62 65 20 69  .** it will be i
95d0: 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 72  nvoked when ther
95e0: 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
95f0: 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69  tion..** If SQLi
9600: 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
9610: 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
9620: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6f 75  busy handler cou
9630: 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20  ld result in.** 
9640: 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
9650: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
9660: 54 45 5f 42 55 53 59 5d 20 69 6e 73 74 65 61 64  TE_BUSY] instead
9670: 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
9680: 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
9690: 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
96a0: 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
96b0: 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
96c0: 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
96d0: 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
96e0: 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
96f0: 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
9700: 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
9710: 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
9720: 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
9730: 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
9740: 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
9750: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
9760: 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
9770: 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
9780: 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
9790: 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
97a0: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
97b0: 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
97c0: 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
97d0: 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
97e0: 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
97f0: 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
9800: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
9810: 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
9820: 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
9830: 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
9840: 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
9850: 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
9860: 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
9870: 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
9880: 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
9890: 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
98a0: 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
98b0: 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
98c0: 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
98d0: 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
98e0: 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
98f0: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
9900: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
9910: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
9920: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
9930: 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
9940: 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
9950: 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 77 68 65 6e  RR_BLOCKED] when
9960: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 69 6e  .** SQLite is in
9970: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
9980: 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
9990: 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
99a0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
99b0: 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
99c0: 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
99d0: 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
99e0: 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
99f0: 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
9a00: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
9a10: 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
9a20: 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
9a30: 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
9a40: 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
9a50: 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
9a60: 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
9a70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9a80: 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
9a90: 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
9aa0: 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74   readers.  If it
9ab0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
9ac0: 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
9ad0: 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
9ae0: 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
9af0: 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
9b00: 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
9b10: 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
9b20: 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
9b30: 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
9b40: 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
9b50: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
9b60: 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
9b70: 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
9b80: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54  ERR_BLOCKED].  T
9b90: 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
9ba0: 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
9bb0: 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
9bc0: 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
9bd0: 63 68 61 6e 67 65 73 2e 20 53 65 65 20 74 68 65  changes. See the
9be0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
9bf0: 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f  p://www.sqlite.o
9c00: 72 67 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  rg/cvstrac/wiki?
9c10: 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
9c20: 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
9c30: 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
9c40: 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
9c50: 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
9c60: 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
9c70: 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
9c80: 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09  s important..**.
9c90: 0a 2a 2a 20 53 71 6c 69 74 65 20 69 73 20 72 65  .** Sqlite is re
9ca0: 2d 65 6e 74 72 61 6e 74 2c 20 73 6f 20 74 68 65  -entrant, so the
9cb0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 61   busy handler ma
9cc0: 79 20 73 74 61 72 74 20 61 20 6e 65 77 20 71 75  y start a new qu
9cd0: 65 72 79 2e 20 0a 2a 2a 20 28 49 74 20 69 73 20  ery. .** (It is 
9ce0: 6e 6f 74 20 63 6c 65 61 72 20 77 68 79 20 61 6e  not clear why an
9cf0: 79 6f 6e 65 20 77 6f 75 6c 64 20 65 76 65 72 79  yone would every
9d00: 20 77 61 6e 74 20 74 6f 20 64 6f 20 74 68 69 73   want to do this
9d10: 2c 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 61  , but it.** is a
9d20: 6c 6c 6f 77 65 64 2c 20 69 6e 20 74 68 65 6f 72  llowed, in theor
9d30: 79 2e 29 20 20 42 75 74 20 74 68 65 20 62 75 73  y.)  But the bus
9d40: 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 6e 6f  y handler may no
9d50: 74 20 63 6c 6f 73 65 20 74 68 65 0a 2a 2a 20 64  t close the.** d
9d60: 61 74 61 62 61 73 65 2e 20 20 43 6c 6f 73 69 6e  atabase.  Closin
9d70: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9d80: 72 6f 6d 20 61 20 62 75 73 79 20 68 61 6e 64 6c  rom a busy handl
9d90: 65 72 20 77 69 6c 6c 20 64 65 6c 65 74 65 20 0a  er will delete .
9da0: 2a 2a 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ** data structur
9db0: 65 73 20 6f 75 74 20 66 72 6f 6d 20 75 6e 64 65  es out from unde
9dc0: 72 20 74 68 65 20 65 78 65 63 75 74 69 6e 67 20  r the executing 
9dd0: 71 75 65 72 79 20 61 6e 64 20 77 69 6c 6c 20 0a  query and will .
9de0: 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 73 75  ** probably resu
9df0: 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
9e00: 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
9e10: 68 65 72 20 72 75 6e 74 69 6d 65 20 65 72 72 6f  her runtime erro
9e20: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63  r..**.** There c
9e30: 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
9e40: 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
9e50: 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
9e60: 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  h database.** co
9e70: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 74 69  nnection.  Setti
9e80: 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
9e90: 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
9ea0: 20 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e 0a 2a   previous one..*
9eb0: 2a 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c  * Note that call
9ec0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
9ed0: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 69 6c  y_timeout()] wil
9ee0: 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
9ef0: 65 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 79 20  ear.** the busy 
9f00: 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  handler..**.** W
9f10: 68 65 6e 20 6f 70 65 72 61 74 69 6e 67 20 69 6e  hen operating in
9f20: 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
9f30: 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20  _shared_cache | 
9f40: 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
9f50: 65 5d 2c 0a 2a 2a 20 6f 6e 6c 79 20 61 20 73 69  e],.** only a si
9f60: 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
9f70: 72 20 63 61 6e 20 62 65 20 64 65 66 69 6e 65 64  r can be defined
9f80: 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61   for each databa
9f90: 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 53 6f 20 69  se file..** So i
9fa0: 66 20 74 77 6f 20 64 61 74 61 62 61 73 65 20 63  f two database c
9fb0: 6f 6e 6e 65 63 74 69 6f 6e 73 20 73 68 61 72 65  onnections share
9fc0: 20 61 20 73 69 6e 67 6c 65 20 63 61 63 68 65 2c   a single cache,
9fd0: 20 74 68 65 6e 20 63 68 61 6e 67 69 6e 67 0a 2a   then changing.*
9fe0: 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
9ff0: 65 72 20 6f 6e 20 6f 6e 65 20 63 6f 6e 6e 65 63  er on one connec
a000: 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 73 6f 20 63  tion will also c
a010: 68 61 6e 67 65 20 74 68 65 20 62 75 73 79 0a 2a  hange the busy.*
a020: 2a 20 68 61 6e 64 6c 65 72 20 69 6e 20 74 68 65  * handler in the
a030: 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f   other connectio
a040: 6e 2e 20 20 54 68 65 20 62 75 73 79 20 68 61 6e  n.  The busy han
a050: 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 0a  dler is invoked.
a060: 2a 2a 20 69 6e 20 74 68 65 20 74 68 72 65 61 64  ** in the thread
a070: 20 74 68 61 74 20 77 61 73 20 72 75 6e 6e 69 6e   that was runnin
a080: 67 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54  g when the SQLIT
a090: 45 5f 42 55 53 59 20 77 61 73 20 68 69 74 2e 0a  E_BUSY was hit..
a0a0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
a0b0: 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
a0c0: 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
a0d0: 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
a0e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a0f0: 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
a100: 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eout.**.** This 
a110: 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 62  routine sets a b
a120: 75 73 79 20 68 61 6e 64 6c 65 72 20 74 68 61 74  usy handler that
a130: 20 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77 68   sleeps for a wh
a140: 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61  ile when a.** ta
a150: 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
a160: 54 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c  The handler will
a170: 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
a180: 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20  times until .** 
a190: 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
a1a0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
a1b0: 65 65 70 69 6e 67 20 68 61 76 65 20 62 65 65 6e  eeping have been
a1c0: 20 64 6f 6e 65 2e 20 20 41 66 74 65 72 0a 2a 2a   done.  After.**
a1d0: 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
a1e0: 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20  ds of sleeping, 
a1f0: 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
a200: 72 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a 20 63  rns 0 which.** c
a210: 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
a220: 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
a230: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
a240: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
a250: 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
a260: 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
a270: 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
a280: 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
a290: 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
a2a0: 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
a2b0: 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
a2c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
a2d0: 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
a2e0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
a2f0: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
a300: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
a310: 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74  ection.  If anot
a320: 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
a330: 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 0a 2a   was defined  .*
a340: 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  * (using [sqlite
a350: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
a360: 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
a370: 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
a380: 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
a390: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
a3a0: 63 6c 65 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74 20  cleared..*/.int 
a3b0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
a3c0: 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
a3d0: 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
a3e0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
a3f0: 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
a400: 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
a410: 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6e 65 78  s.**.** This nex
a420: 74 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 63  t routine is a c
a430: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
a440: 65 72 20 61 72 6f 75 6e 64 20 5b 73 71 6c 69 74  er around [sqlit
a450: 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2a 20 49  e3_exec()]..** I
a460: 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
a470: 6e 67 20 61 20 75 73 65 72 2d 73 75 70 70 6c 69  ng a user-suppli
a480: 65 64 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 20  ed callback for 
a490: 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 0a  each row of the.
a4a0: 2a 2a 20 72 65 73 75 6c 74 2c 20 74 68 69 73 20  ** result, this 
a4b0: 72 6f 75 74 69 6e 65 20 72 65 6d 65 6d 62 65 72  routine remember
a4c0: 73 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68  s each row of th
a4d0: 65 20 72 65 73 75 6c 74 20 69 6e 20 6d 65 6d 6f  e result in memo
a4e0: 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ry.** obtained f
a4f0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
a500: 6c 6f 63 28 29 5d 2c 20 74 68 65 6e 20 72 65 74  loc()], then ret
a510: 75 72 6e 73 20 61 6c 6c 20 6f 66 20 74 68 65 20  urns all of the 
a520: 72 65 73 75 6c 74 20 61 66 74 65 72 20 74 68 65  result after the
a530: 0a 2a 2a 20 71 75 65 72 79 20 68 61 73 20 66 69  .** query has fi
a540: 6e 69 73 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 41  nished. .**.** A
a550: 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 73 75  s an example, su
a560: 70 70 6f 73 65 20 74 68 65 20 71 75 65 72 79 20  ppose the query 
a570: 72 65 73 75 6c 74 20 77 68 65 72 65 20 74 68 69  result where thi
a580: 73 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 3c  s table:.**.** <
a590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
a5a0: 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
a5b0: 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
a5c0: 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
a5d0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
a5e0: 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
a5f0: 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
a600: 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
a610: 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
a620: 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
a630: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
a640: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20  quote>.**.** If 
a650: 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
a660: 20 77 65 72 65 20 26 61 7a 52 65 73 75 6c 74 20   were &azResult 
a670: 74 68 65 6e 20 61 66 74 65 72 20 74 68 65 20 66  then after the f
a680: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a  unction returns.
a690: 2a 2a 20 61 7a 52 65 73 75 6c 74 20 77 69 6c 6c  ** azResult will
a6a0: 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 66 6f 6c   contain the fol
a6b0: 6c 6f 77 69 6e 67 20 64 61 74 61 3a 0a 2a 2a 0a  lowing data:.**.
a6c0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
a6d0: 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
a6e0: 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
a6f0: 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
a700: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
a710: 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
a720: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
a730: 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
a740: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
a750: 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
a760: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
a770: 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
a780: 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
a790: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
a7a0: 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
a7b0: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
a7c0: 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
a7d0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
a7e0: 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
a7f0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
a800: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 69  uote>.**.** Noti
a810: 63 65 20 74 68 61 74 20 74 68 65 72 65 20 69 73  ce that there is
a820: 20 61 6e 20 65 78 74 72 61 20 72 6f 77 20 6f 66   an extra row of
a830: 20 64 61 74 61 20 63 6f 6e 74 61 69 6e 69 6e 67   data containing
a840: 20 74 68 65 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 68   the column.** h
a850: 65 61 64 65 72 73 2e 20 20 42 75 74 20 74 68 65  eaders.  But the
a860: 20 2a 6e 72 6f 77 20 72 65 74 75 72 6e 20 76 61   *nrow return va
a870: 6c 75 65 20 69 73 20 73 74 69 6c 6c 20 33 2e 20  lue is still 3. 
a880: 20 2a 6e 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20   *ncolumn is.** 
a890: 73 65 74 20 74 6f 20 32 2e 20 20 49 6e 20 67 65  set to 2.  In ge
a8a0: 6e 65 72 61 6c 2c 20 74 68 65 20 6e 75 6d 62 65  neral, the numbe
a8b0: 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 73 65  r of values inse
a8c0: 72 74 65 64 20 69 6e 74 6f 20 61 7a 52 65 73 75  rted into azResu
a8d0: 6c 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 28 28  lt.** will be ((
a8e0: 2a 6e 72 6f 77 29 20 2b 20 31 29 2a 28 2a 6e 63  *nrow) + 1)*(*nc
a8f0: 6f 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a 2a 20 41 66  olumn)..**.** Af
a900: 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ter the calling 
a910: 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e  function has fin
a920: 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20  ished using the 
a930: 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c  result, it shoul
a940: 64 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 72  d .** pass the r
a950: 65 73 75 6c 74 20 64 61 74 61 20 70 6f 69 6e 74  esult data point
a960: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
a970: 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
a980: 64 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61  der to .** relea
a990: 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
a9a0: 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64  at was malloc-ed
a9b0: 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
a9c0: 65 20 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73  e way the .** [s
a9d0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
a9e0: 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 63 61   happens, the ca
a9f0: 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  lling function m
aa00: 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
aa10: 61 6c 6c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  all .** [sqlite3
aa20: 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
aa30: 79 2e 20 20 4f 6e 6c 79 20 5b 73 71 6c 69 74 65  y.  Only [sqlite
aa40: 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
aa50: 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
aa60: 73 65 20 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  se .** the memor
aa70: 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
aa80: 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
aa90: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
aaa0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
aab0: 20 74 68 65 20 73 61 6d 65 20 61 73 20 66 72 6f   the same as fro
aac0: 6d 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  m [sqlite3_exec(
aad0: 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
aae0: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
aaf0: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
ab00: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
ab10: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
ab20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c  const char *sql,
ab30: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
ab40: 20 62 65 20 65 78 65 63 75 74 65 64 20 2a 2f 0a   be executed */.
ab50: 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74    char ***result
ab60: 70 2c 20 20 20 20 20 20 20 2f 2a 20 52 65 73 75  p,       /* Resu
ab70: 6c 74 20 77 72 69 74 74 65 6e 20 74 6f 20 61 20  lt written to a 
ab80: 63 68 61 72 20 2a 5b 5d 20 20 74 68 61 74 20 74  char *[]  that t
ab90: 68 69 73 20 70 6f 69 6e 74 73 20 74 6f 20 2a 2f  his points to */
aba0: 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20  .  int *nrow,   
abb0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
abc0: 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
abd0: 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
abe0: 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d  */.  int *ncolum
abf0: 6e 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  n,          /* N
ac00: 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
ac10: 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
ac20: 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
ac30: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
ac40: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
ac50: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
ac60: 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
ac70: 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
ac80: 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
ac90: 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
aca0: 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
acb0: 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
acc0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
acd0: 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65  es are workalike
ace0: 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
acf0: 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
ad00: 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
ad10: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
ad20: 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  ibrary..**.** Th
ad30: 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
ad40: 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
ad50: 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
ad60: 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
ad70: 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
ad80: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
ad90: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
ada0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
adb0: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
adc0: 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
add0: 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
ade0: 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
adf0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
ae00: 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73  .  Both routines
ae10: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
ae20: 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
ae30: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
ae40: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
ae50: 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
ae60: 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
ae70: 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
ae80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71  ing..**.** In sq
ae90: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
aea0: 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
aeb0: 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
aec0: 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
aed0: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
aee0: 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
aef0: 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
af00: 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
af10: 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
af20: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
af30: 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
af40: 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
af50: 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 4e  st parameter.  N
af60: 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
af70: 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
af80: 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
af90: 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
afa0: 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20  om snprintf().  
afb0: 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
afc0: 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
afd0: 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
afe0: 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
aff0: 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
b000: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
b010: 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74  ty.  Note also t
b020: 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
b030: 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
b040: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
b050: 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
b060: 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
b070: 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
b080: 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
b090: 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
b0a0: 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  r.  We admit tha
b0b0: 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
b0c0: 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
b0d0: 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
b0e0: 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
b0f0: 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
b100: 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
b110: 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
b120: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
b130: 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
b140: 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
b150: 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
b160: 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20  ..**.** As long 
b170: 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
b180: 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
b190: 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
b1a0: 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
b1b0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
b1c0: 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
b1d0: 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
b1e0: 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a  ted.  The first.
b1f0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
b200: 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
b210: 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
b220: 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
b230: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
b240: 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
b250: 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
b260: 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
b270: 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
b280: 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
b290: 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
b2a0: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
b2b0: 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
b2c0: 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
b2d0: 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
b2e0: 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
b2f0: 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
b300: 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
b310: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
b320: 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
b330: 6e 74 66 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  ntf formatting o
b340: 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
b350: 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
b360: 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
b370: 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
b380: 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
b390: 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
b3a0: 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
b3b0: 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
b3c0: 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
b3d0: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
b3e0: 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
b3f0: 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
b400: 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
b410: 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
b420: 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
b430: 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
b440: 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
b450: 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e  ral.  By doublin
b460: 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
b470: 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
b480: 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
b490: 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
b4a0: 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
b4b0: 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
b4c0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
b4d0: 61 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73  ample, so some s
b4e0: 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 63  tring variable c
b4f0: 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
b500: 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
b510: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
b520: 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
b530: 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
b540: 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
b550: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
b560: 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
b570: 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
b580: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
b590: 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
b5a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
b5b0: 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
b5c0: 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
b5d0: 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
b5e0: 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
b5f0: 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
b600: 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
b610: 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
b620: 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
b630: 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
b640: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
b650: 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
b660: 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
b670: 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
b680: 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
b690: 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
b6a0: 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
b6b0: 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
b6c0: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
b6d0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
b6e0: 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
b6f0: 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
b700: 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
b710: 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
b720: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
b730: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
b740: 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
b750: 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
b760: 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
b770: 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
b780: 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
b790: 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
b7a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
b7b0: 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
b7c0: 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
b7d0: 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
b7e0: 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
b7f0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
b800: 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
b810: 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
b820: 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
b830: 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
b840: 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c  you.** should al
b850: 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
b860: 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
b870: 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
b880: 74 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20  to a string .** 
b890: 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54  literal..**.** T
b8a0: 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
b8b0: 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
b8c0: 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
b8d0: 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
b8e0: 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
b8f0: 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
b900: 73 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20 74  string.  Or if t
b910: 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
b920: 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  the argument.** 
b930: 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
b940: 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
b950: 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
b960: 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 20  "NULL" (without 
b970: 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73  single.** quotes
b980: 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  ) in place of th
b990: 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f  e %Q option.  So
b9a0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
b9b0: 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
b9c0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
b9d0: 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
b9e0: 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
b9f0: 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
ba00: 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
ba10: 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
ba20: 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
ba30: 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
ba40: 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
ba50: 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
ba60: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
ba70: 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
ba80: 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
ba90: 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
baa0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
bab0: 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
bac0: 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
bad0: 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
bae0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
baf0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22  ..**.** The "%z"
bb00: 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
bb10: 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79  on works exactly
bb20: 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20   like "%s" with 
bb30: 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
bb40: 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
bb50: 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
bb60: 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
bb70: 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
bb80: 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
bb90: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
bba0: 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
bbb0: 67 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  g..*/.char *sqli
bbc0: 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
bbd0: 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
bbe0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
bbf0: 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
bc00: 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
bc10: 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
bc20: 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
bc30: 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
bc40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bc50: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
bc60: 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
bc70: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
bc80: 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
bc90: 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
bca0: 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
bcb0: 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
bcc0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
bcd0: 65 64 73 2e 20 28 53 65 65 20 74 68 65 20 65 78  eds. (See the ex
bce0: 63 65 70 74 69 6f 6e 20 62 65 6c 6f 77 2e 29 0a  ception below.).
bcf0: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69  ** The default i
bd00: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
bd10: 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61   of the memory a
bd20: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
bd30: 74 65 6d 20 75 73 65 73 20 74 68 65 20 6d 61 6c  tem uses the mal
bd40: 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
bd50: 0a 2a 2a 20 61 6e 64 20 66 72 65 65 28 29 20 70  .** and free() p
bd60: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73  rovided by the s
bd70: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
bd80: 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20  y.  However, if 
bd90: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 63 6f  .** SQLite is co
bda0: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
bdb0: 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72 65 70  following C prep
bdc0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
bdd0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
bde0: 3e 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  > SQLITE_OMIT_ME
bdf0: 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
be00: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
be10: 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 69 6d 70 6c  .** then no impl
be20: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 70 72  ementation is pr
be30: 6f 76 69 64 65 64 20 66 6f 72 20 74 68 65 73 65  ovided for these
be40: 20 72 6f 75 74 69 6e 65 73 20 62 79 0a 2a 2a 20   routines by.** 
be50: 53 51 4c 69 74 65 2e 20 20 54 68 65 20 61 70 70  SQLite.  The app
be60: 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 6c 69  lication that li
be70: 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69  nks against SQLi
be80: 74 65 20 69 73 0a 2a 2a 20 65 78 70 65 63 74 65  te is.** expecte
be90: 64 20 74 6f 20 70 72 6f 76 69 64 65 20 69 74 73  d to provide its
bea0: 20 6f 77 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74   own implementat
beb0: 69 6f 6e 2e 20 20 49 66 20 74 68 65 20 61 70 70  ion.  If the app
bec0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73  lication.** does
bed0: 20 70 72 6f 76 69 64 65 20 69 74 73 20 6f 77 6e   provide its own
bee0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
bef0: 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
bf00: 65 73 2c 20 74 68 65 6e 0a 2a 2a 20 69 74 20 6d  es, then.** it m
bf10: 75 73 74 20 61 6c 73 6f 20 70 72 6f 76 69 64 65  ust also provide
bf20: 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
bf30: 6f 6e 73 20 66 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ons for.** [sqli
bf40: 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
bf50: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ()], [sqlite3_me
bf60: 6d 6f 72 79 5f 75 73 65 64 28 29 5d 2c 20 61 6e  mory_used()], an
bf70: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
bf80: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
bf90: 5d 2e 20 20 54 68 65 20 61 6c 74 65 72 6e 61 74  ].  The alternat
bfa0: 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
bfb0: 6f 6e 73 0a 2a 2a 20 66 6f 72 20 74 68 65 73 65  ons.** for these
bfc0: 20 6c 61 73 74 20 74 68 72 65 65 20 72 6f 75 74   last three rout
bfd0: 69 6e 65 73 20 6e 65 65 64 20 6e 6f 74 20 61 63  ines need not ac
bfe0: 74 75 61 6c 6c 79 20 77 6f 72 6b 2c 20 62 75 74  tually work, but
bff0: 0a 2a 2a 20 73 74 75 62 20 66 75 6e 63 74 69 6f  .** stub functio
c000: 6e 73 20 61 74 20 6c 65 61 73 74 20 61 72 65 20  ns at least are 
c010: 6e 65 65 64 65 64 20 74 6f 20 73 74 61 74 69 73  needed to statis
c020: 66 79 20 74 68 65 20 6c 69 6e 6b 65 72 2e 0a 2a  fy the linker..*
c030: 2a 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20 63  * SQLite never c
c040: 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 6d 65  alls [sqlite3_me
c050: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
c060: 5d 20 69 74 73 65 6c 66 2c 20 62 75 74 0a 2a 2a  ] itself, but.**
c070: 20 74 68 65 20 73 79 6d 62 6f 6c 20 69 73 20 69   the symbol is i
c080: 6e 63 6c 75 64 65 64 20 69 6e 20 61 20 74 61 62  ncluded in a tab
c090: 6c 65 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  le as part of th
c0a0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  e.** [sqlite3_lo
c0b0: 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
c0c0: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 0a  interface.  The.
c0d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
c0e0: 72 79 5f 61 6c 61 72 6d 28 29 5d 20 61 6e 64 20  ry_alarm()] and 
c0f0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
c100: 75 73 65 64 28 29 5d 20 69 6e 74 65 72 66 61 63  used()] interfac
c110: 65 73 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  es.** are called
c120: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66   by [sqlite3_sof
c130: 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 20  t_heap_limit()] 
c140: 61 6e 64 20 77 6f 72 6b 69 6e 67 20 69 6d 70 6c  and working impl
c150: 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f  ementations.** o
c160: 66 20 62 6f 74 68 20 72 6f 75 74 69 6e 65 73 20  f both routines 
c170: 6d 75 73 74 20 62 65 20 70 72 6f 76 69 64 65 64  must be provided
c180: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66   if [sqlite3_sof
c190: 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a  t_heap_limit()].
c1a0: 2a 2a 20 69 73 20 74 6f 20 6f 70 65 72 61 74 65  ** is to operate
c1b0: 20 63 6f 72 72 65 63 74 6c 79 2e 0a 2a 2a 0a 2a   correctly..**.*
c1c0: 2a 20 3c 62 3e 45 78 63 65 70 74 69 6f 6e 3a 3c  * <b>Exception:<
c1d0: 2f 62 3e 20 54 68 65 20 77 69 6e 64 6f 77 73 20  /b> The windows 
c1e0: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
c1f0: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
c200: 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
c210: 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
c220: 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
c230: 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
c240: 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
c250: 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
c260: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
c270: 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
c280: 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
c290: 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
c2a0: 69 63 75 6c 61 72 20 77 69 6e 64 6f 77 73 0a 2a  icular windows.*
c2b0: 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
c2c0: 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
c2d0: 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
c2e0: 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
c2f0: 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
c300: 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
c310: 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
c320: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
c330: 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
c340: 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 76  ITE_NOMEM]..*/.v
c350: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
c360: 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  loc(int);.void *
c370: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
c380: 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
c390: 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
c3a0: 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
c3b0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
c3c0: 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
c3d0: 69 63 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64 64  ics.**.** In add
c3e0: 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 62 61 73  ition to the bas
c3f0: 69 63 20 74 68 72 65 65 20 61 6c 6c 6f 63 61 74  ic three allocat
c400: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a  ion routines .**
c410: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
c420: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
c430: 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
c440: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
c450: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
c460: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
c470: 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  em included with
c480: 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 73   the SQLite.** s
c490: 6f 75 72 63 65 73 20 70 72 6f 76 69 64 65 73 20  ources provides 
c4a0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  the interfaces s
c4b0: 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 0a 2a  hown below..**.*
c4c0: 2a 20 54 68 65 20 66 69 72 73 74 20 6f 66 20 74  * The first of t
c4d0: 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
c4e0: 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 6d  s returns the am
c4f0: 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 0a  ount of memory .
c500: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ** currently out
c510: 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
c520: 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
c530: 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a  ).  The second.*
c540: 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 61  * returns the la
c550: 72 67 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65  rgest instantane
c560: 6f 75 73 20 61 6d 6f 75 6e 74 20 6f 66 20 6f 75  ous amount of ou
c570: 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 6d 65 6d  tstanding.** mem
c580: 6f 72 79 2e 20 20 54 68 65 20 68 69 67 68 77 61  ory.  The highwa
c590: 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
c5a0: 74 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  t if the argumen
c5b0: 74 20 69 73 0a 2a 2a 20 74 72 75 65 2e 0a 2a 2a  t is.** true..**
c5c0: 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
c5d0: 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
c5e0: 72 6f 75 74 69 6e 65 73 20 69 6e 20 74 68 65 20  routines in the 
c5f0: 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 69  SQLite core.** i
c600: 73 20 6f 6d 69 74 74 65 64 20 69 66 20 74 68 65  s omitted if the
c610: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
c620: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
c630: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4d 49 54  e.** SQLITE_OMIT
c640: 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
c650: 4f 4e 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  ON macro defined
c660: 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
c670: 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
c680: 69 6f 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 53  ion that links S
c690: 51 4c 69 74 65 20 6d 75 73 74 20 70 72 6f 76 69  QLite must provi
c6a0: 64 65 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 61 6c  de its own.** al
c6b0: 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d  ternative implem
c6c0: 65 6e 74 61 74 69 6f 6e 2e 20 20 53 65 65 20 74  entation.  See t
c6d0: 68 65 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  he documentation
c6e0: 20 6f 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   on.** [sqlite3_
c6f0: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 61 64  malloc()] for ad
c700: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
c710: 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  tion..*/.sqlite3
c720: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
c730: 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
c740: 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
c750: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
c760: 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
c770: 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
c780: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
c790: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 41 6c 61 72   Allocation Alar
c7a0: 6d 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  ms.**.** The [sq
c7b0: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
c7c0: 72 6d 5d 20 72 6f 75 74 69 6e 65 20 69 73 20 75  rm] routine is u
c7d0: 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a  sed to register.
c7e0: 2a 2a 20 61 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  ** a callback on
c7f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c800: 6f 6e 20 65 76 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  on events..**.**
c810: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
c820: 67 69 73 74 65 72 73 20 6f 72 20 63 6c 65 61 72  gisters or clear
c830: 73 20 61 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  s a callbacks th
c840: 61 74 20 66 69 72 65 73 20 77 68 65 6e 0a 2a 2a  at fires when.**
c850: 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d   the amount of m
c860: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
c870: 65 78 63 65 65 64 73 20 69 54 68 72 65 73 68 6f  exceeds iThresho
c880: 6c 64 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 61 20 73  ld.  Only.** a s
c890: 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ingle callback c
c8a0: 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
c8b0: 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
c8c0: 68 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  h call.** to [sq
c8d0: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
c8e0: 72 6d 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73  rm()] overwrites
c8f0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
c900: 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 63  llback..** The c
c910: 61 6c 6c 62 61 63 6b 20 69 73 20 64 69 73 61 62  allback is disab
c920: 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 78  led by setting x
c930: 43 61 6c 6c 62 61 63 6b 20 74 6f 20 61 20 4e 55  Callback to a NU
c940: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 0a 2a  LL.** pointer..*
c950: 2a 20 0a 2a 2a 20 54 68 65 20 70 61 72 61 6d 65  * .** The parame
c960: 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ters to the call
c970: 62 61 63 6b 20 61 72 65 20 74 68 65 20 70 41 72  back are the pAr
c980: 67 20 76 61 6c 75 65 2c 20 74 68 65 20 0a 2a 2a  g value, the .**
c990: 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
c9a0: 79 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  y currently in u
c9b0: 73 65 2c 20 61 6e 64 20 74 68 65 20 73 69 7a 65  se, and the size
c9c0: 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 63   of the.** alloc
c9d0: 61 74 69 6f 6e 20 74 68 61 74 20 70 72 6f 76 6f  ation that provo
c9e0: 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ked the callback
c9f0: 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  .  The callback 
ca00: 77 69 6c 6c 0a 2a 2a 20 70 72 65 73 75 6d 61 62  will.** presumab
ca10: 6c 79 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ly invoke [sqlit
ca20: 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72  e3_free()] to fr
ca30: 65 65 20 75 70 20 6d 65 6d 6f 72 79 20 73 70 61  ee up memory spa
ca40: 63 65 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  ce..** The callb
ca50: 61 63 6b 20 6d 61 79 20 69 6e 76 6f 6b 65 20 5b  ack may invoke [
ca60: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
ca70: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
ca80: 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 62 75 74 20  alloc()].** but 
ca90: 69 66 20 69 74 20 64 6f 65 73 2c 20 6e 6f 20 61  if it does, no a
caa0: 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61  dditional callba
cab0: 63 6b 73 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  cks will be invo
cac0: 6b 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 72 65  ked by.** the re
cad0: 63 75 72 73 69 76 65 20 63 61 6c 6c 73 2e 0a 2a  cursive calls..*
cae0: 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
caf0: 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
cb00: 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  t()] interface w
cb10: 6f 72 6b 73 20 62 79 20 72 65 67 69 73 74 65 72  orks by register
cb20: 69 6e 67 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20  ing.** a memory 
cb30: 61 6c 61 72 6d 20 61 74 20 74 68 65 20 73 6f 66  alarm at the sof
cb40: 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64  t heap limit and
cb50: 20 69 6e 76 6f 6b 69 6e 67 20 0a 2a 2a 20 5b 73   invoking .** [s
cb60: 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
cb70: 65 6d 6f 72 79 28 29 5d 20 69 6e 20 74 68 65 20  emory()] in the 
cb80: 61 6c 61 72 6d 20 63 61 6c 6c 62 61 63 6b 2e 20  alarm callback. 
cb90: 20 41 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   Application.** 
cba0: 70 72 6f 67 72 61 6d 73 20 73 68 6f 75 6c 64 20  programs should 
cbb0: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 75  not attempt to u
cbc0: 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
cbd0: 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 0a  memory_alarm()].
cbe0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  ** interface bec
cbf0: 61 75 73 65 20 64 6f 69 6e 67 20 73 6f 20 77 69  ause doing so wi
cc00: 6c 6c 20 69 6e 74 65 72 66 65 72 65 20 77 69 74  ll interfere wit
cc10: 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
cc20: 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
cc30: 74 28 29 5d 20 6d 6f 64 75 6c 65 2e 20 20 54 68  t()] module.  Th
cc40: 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
cc50: 65 78 70 6f 73 65 64 0a 2a 2a 20 6f 6e 6c 79 20  exposed.** only 
cc60: 73 6f 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  so that applicat
cc70: 69 6f 6e 73 20 63 61 6e 20 70 72 6f 76 69 64 65  ions can provide
cc80: 20 74 68 65 69 72 20 6f 77 6e 0a 2a 2a 20 61 6c   their own.** al
cc90: 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d  ternative implem
cca0: 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
ccb0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69 73  e SQLite core is
ccc0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
ccd0: 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  h SQLITE_OMIT_ME
cce0: 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 2e  MORY_ALLOCATION.
ccf0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
cd00: 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 0a 20 20  memory_alarm(.  
cd10: 76 6f 69 64 28 2a 78 43 61 6c 6c 62 61 63 6b 29  void(*xCallback)
cd20: 28 76 6f 69 64 20 2a 70 41 72 67 2c 20 73 71 6c  (void *pArg, sql
cd30: 69 74 65 33 5f 69 6e 74 36 34 20 75 73 65 64 2c  ite3_int64 used,
cd40: 20 69 6e 74 20 4e 29 2c 0a 20 20 76 6f 69 64 20   int N),.  void 
cd50: 2a 70 41 72 67 2c 0a 20 20 73 71 6c 69 74 65 33  *pArg,.  sqlite3
cd60: 5f 69 6e 74 36 34 20 69 54 68 72 65 73 68 6f 6c  _int64 iThreshol
cd70: 64 0a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d.);.../*.** CAP
cd80: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
cd90: 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
cda0: 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 2a 0a  n Callbacks.***.
cdb0: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
cdc0: 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68  registers a auth
cdd0: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
cde0: 77 69 74 68 20 74 68 65 20 53 51 4c 69 74 65 20  with the SQLite 
cdf0: 6c 69 62 72 61 72 79 2e 20 20 0a 2a 2a 20 54 68  library.  .** Th
ce00: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
ce10: 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
ce20: 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
ce30: 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
ce40: 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
ce50: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
ce60: 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
ce70: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
ce80: 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
ce90: 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
cea0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
ceb0: 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
cec0: 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
ced0: 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
cee0: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
cef0: 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
cf00: 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
cf10: 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
cf20: 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
cf30: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
cf40: 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
cf50: 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
cf60: 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
cf70: 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75  allowed.  The au
cf80: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
cf90: 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
cfa0: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 74 6f 20  rn SQLITE_OK to 
cfb0: 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
cfc0: 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
cfd0: 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
cfe0: 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
cff0: 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
d000: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
d010: 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
d020: 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
d030: 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
d040: 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
d050: 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
d060: 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
d070: 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
d080: 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 44 65 70 65  or.  .**.** Depe
d090: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 61 63 74  nding on the act
d0a0: 69 6f 6e 2c 20 74 68 65 20 5b 53 51 4c 49 54 45  ion, the [SQLITE
d0b0: 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53 51  _IGNORE] and [SQ
d0c0: 4c 49 54 45 5f 44 45 4e 59 5d 20 72 65 74 75 72  LITE_DENY] retur
d0d0: 6e 0a 2a 2a 20 63 6f 64 65 73 20 6d 69 67 68 74  n.** codes might
d0e0: 20 6d 65 61 6e 20 73 6f 6d 65 74 68 69 6e 67 20   mean something 
d0f0: 64 69 66 66 65 72 65 6e 74 20 6f 72 20 74 68 65  different or the
d100: 79 20 6d 69 67 68 74 20 6d 65 61 6e 20 74 68 65  y might mean the
d110: 20 73 61 6d 65 0a 2a 2a 20 74 68 69 6e 67 2e 20   same.** thing. 
d120: 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69   If the action i
d130: 73 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  s, for example, 
d140: 74 6f 20 70 65 72 66 6f 72 6d 20 61 20 64 65 6c  to perform a del
d150: 65 74 65 20 6f 70 65 72 74 69 6f 6e 2c 0a 2a 2a  ete opertion,.**
d160: 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 49 47   then [SQLITE_IG
d170: 4e 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c 49 54  NORE] and [SQLIT
d180: 45 5f 44 45 4e 59 5d 20 62 6f 74 68 20 63 61 75  E_DENY] both cau
d190: 73 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  se the statement
d1a0: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 0a 2a 2a 20   compilation.** 
d1b0: 74 6f 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  to fail with an 
d1c0: 65 72 72 6f 72 2e 20 20 42 75 74 20 69 66 20 74  error.  But if t
d1d0: 68 65 20 61 63 74 69 6f 6e 20 69 73 20 74 6f 20  he action is to 
d1e0: 72 65 61 64 20 61 20 73 70 65 63 69 66 69 63 20  read a specific 
d1f0: 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 72 6f 6d 20 61  column.** from a
d200: 20 73 70 65 63 69 66 69 63 20 74 61 62 6c 65 2c   specific table,
d210: 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 44 45   then [SQLITE_DE
d220: 4e 59 5d 20 77 69 6c 6c 20 63 61 75 73 65 20 74  NY] will cause t
d230: 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 74 61  he entire.** sta
d240: 74 65 6d 65 6e 74 20 74 6f 20 66 61 69 6c 20 62  tement to fail b
d250: 75 74 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ut [SQLITE_IGNOR
d260: 45 5d 20 77 69 6c 6c 20 63 61 75 73 65 20 61 20  E] will cause a 
d270: 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 62 65  NULL value to be
d280: 0a 2a 2a 20 72 65 61 64 20 69 6e 73 74 65 61 64  .** read instead
d290: 20 6f 66 20 74 68 65 20 61 63 74 75 61 6c 20 63   of the actual c
d2a0: 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a  olumn value..**.
d2b0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
d2c0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
d2d0: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
d2e0: 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
d2f0: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
d300: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
d310: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
d320: 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
d330: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
d340: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
d350: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
d360: 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c 49  nteger .** [SQLI
d370: 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
d380: 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
d390: 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63  ifies the partic
d3a0: 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 74  ular action.** t
d3b0: 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
d3c0: 20 20 54 68 65 20 61 76 61 69 6c 61 62 6c 65 20    The available 
d3d0: 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 61 72 65  action codes are
d3e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  .** [SQLITE_COPY
d3f0: 20 7c 20 64 6f 63 75 6d 65 6e 74 65 64 20 73 65   | documented se
d400: 70 61 72 61 74 65 6c 79 5d 2e 20 20 54 68 65 20  parately].  The 
d410: 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
d420: 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  xth.** parameter
d430: 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
d440: 6b 20 61 72 65 20 73 74 72 69 6e 67 73 20 74 68  k are strings th
d450: 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
d460: 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
d470: 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
d480: 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
d490: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ed..**.** An aut
d4a0: 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
d4b0: 77 68 65 6e 20 70 72 65 70 61 72 69 6e 67 20 53  when preparing S
d4c0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
d4d0: 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 0a  om an untrusted.
d4e0: 2a 2a 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ** source, to en
d4f0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
d500: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 64 6f 20  L statements do 
d510: 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
d520: 73 20 64 61 74 61 0a 2a 2a 20 74 68 61 74 20 74  s data.** that t
d530: 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
d540: 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
d550: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  hat they do not 
d560: 74 72 79 20 74 6f 0a 2a 2a 20 65 78 65 63 75 74  try to.** execut
d570: 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
d580: 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
d590: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
d5a0: 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
d5b0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
d5c0: 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
d5d0: 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
d5e0: 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
d5f0: 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
d600: 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
d610: 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
d620: 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
d630: 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
d640: 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
d650: 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
d660: 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
d670: 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
d680: 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
d690: 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
d6a0: 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
d6b0: 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
d6c0: 4c 20 69 73 20 62 65 69 6e 67 20 70 72 65 70 61  L is being prepa
d6d0: 72 65 64 20 74 68 61 74 20 64 69 73 61 6c 6c 6f  red that disallo
d6e0: 77 73 20 65 76 65 72 79 74 68 69 6e 67 0a 2a 2a  ws everything.**
d6f0: 20 65 78 63 65 70 74 20 53 45 4c 45 43 54 20 73   except SELECT s
d700: 74 61 74 65 6d 65 6e 74 73 2e 20 20 0a 2a 2a 0a  tatements.  .**.
d710: 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  ** Only a single
d720: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
d730: 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
d740: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
d750: 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
d760: 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
d770: 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
d780: 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
d790: 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
d7a0: 73 20 63 61 6c 6c 2e 20 20 41 20 4e 55 4c 4c 20  s call.  A NULL 
d7b0: 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73  authorizer means
d7c0: 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69   that no authori
d7d0: 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
d7e0: 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
d7f0: 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74 68  The default auth
d800: 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a  orizer is NULL..
d810: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
d820: 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
d830: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
d840: 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 20 0a  ed only during .
d850: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
d860: 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
d870: 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
d880: 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
d890: 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
d8a0: 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
d8b0: 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
d8c0: 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2f 0a 69  e3_step()]..*/.i
d8d0: 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
d8e0: 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
d8f0: 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
d900: 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
d910: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
d920: 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
d930: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
d940: 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
d950: 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
d960: 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
d970: 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
d980: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
d990: 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
d9a0: 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
d9b0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
d9c0: 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
d9d0: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
d9e0: 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
d9f0: 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
da00: 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
da10: 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
da20: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
da30: 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
da40: 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
da50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
da60: 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
da70: 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
da80: 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
da90: 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
daa0: 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
dab0: 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
dac0: 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
dad0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
dae0: 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
daf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
db00: 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
db10: 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
db20: 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
db30: 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
db40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
db50: 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
db60: 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
db70: 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
db80: 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
db90: 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
dba0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
dbb0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
dbc0: 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
dbd0: 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20 53 51  rizer certain SQ
dbe0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
dbf0: 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
dc00: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
dc10: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
dc20: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
dc30: 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
dc40: 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
dc50: 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
dc60: 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
dc70: 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
dc80: 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
dc90: 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
dca0: 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
dcb0: 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
dcc0: 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
dcd0: 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
dce0: 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
dcf0: 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a 2a  tion is to be .*
dd00: 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
dd10: 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
dd20: 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
dd30: 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
dd40: 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
dd50: 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
dd60: 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
dd70: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
dd80: 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
dd90: 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
dda0: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
ddb0: 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61  ter.  The 5th pa
ddc0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
ddd0: 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
dde0: 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
ddf0: 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
de00: 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
de10: 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  ", .** etc.) if 
de20: 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65  applicable.  The
de30: 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
de40: 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
de50: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
de60: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
de70: 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
de80: 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
de90: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
dea0: 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
deb0: 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
dec0: 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
ded0: 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
dee0: 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70  tly from .** top
def0: 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
df00: 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
df10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
df20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
df30: 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
df40: 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
df50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
df60: 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
df70: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
df80: 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
df90: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
dfa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dfb0: 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
dfc0: 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
dfd0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
dfe0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
dff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e000: 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
e010: 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
e020: 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
e030: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
e040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
e050: 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
e060: 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
e070: 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
e080: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
e090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
e0a0: 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
e0b0: 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
e0c0: 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
e0d0: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
e0e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
e0f0: 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
e100: 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
e110: 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
e120: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
e130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
e140: 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
e150: 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
e160: 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
e170: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
e180: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
e190: 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
e1a0: 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
e1b0: 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
e1c0: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
e1d0: 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
e1e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
e1f0: 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
e200: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
e210: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
e220: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
e230: 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
e240: 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
e250: 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
e260: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
e270: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
e280: 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
e290: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
e2a0: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
e2b0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e2c0: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
e2d0: 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
e2e0: 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
e2f0: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
e300: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
e310: 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
e320: 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
e330: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
e340: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
e350: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
e360: 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
e370: 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
e380: 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
e390: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
e3a0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e3b0: 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
e3c0: 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
e3d0: 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
e3e0: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
e3f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e400: 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
e410: 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
e420: 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
e430: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
e440: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e450: 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
e460: 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
e470: 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
e480: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
e490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e4a0: 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
e4b0: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
e4c0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
e4d0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
e4e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e4f0: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
e500: 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
e510: 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
e520: 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
e530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
e540: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
e550: 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
e560: 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
e570: 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
e580: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
e590: 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
e5a0: 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
e5b0: 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
e5c0: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
e5d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
e5e0: 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
e5f0: 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    22   /* NULL  
e600: 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
e610: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
e620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
e630: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
e640: 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
e650: 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
e660: 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
e670: 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
e680: 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
e690: 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
e6a0: 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
e6b0: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
e6c0: 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
e6d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
e6e0: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
e6f0: 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
e700: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
e710: 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
e720: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
e730: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
e740: 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
e750: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
e760: 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
e770: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
e780: 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
e790: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
e7a0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e7b0: 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
e7c0: 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
e7d0: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
e7e0: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
e7f0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
e800: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
e810: 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
e820: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
e830: 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
e840: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
e850: 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
e860: 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
e870: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
e880: 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
e890: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e8a0: 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
e8b0: 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
e8c0: 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
e8d0: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
e8e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e8f0: 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
e900: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
e910: 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
e920: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
e930: 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
e940: 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
e950: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
e960: 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
e970: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
e980: 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
e990: 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
e9a0: 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
e9b0: 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
e9c0: 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
e9d0: 73 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  s..** The callba
e9e0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
e9f0: 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
ea00: 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
ea10: 6f 6b 65 64 0a 2a 2a 20 61 74 20 74 68 65 20 66  oked.** at the f
ea20: 69 72 73 74 20 5b 73 71 6c 69 74 65 33 5f 73 74  irst [sqlite3_st
ea30: 65 70 28 29 5d 20 66 6f 72 20 74 68 65 20 65 76  ep()] for the ev
ea40: 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 20 53  aluation of an S
ea50: 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
ea60: 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
ea70: 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
ea80: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
ea90: 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
eaa0: 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
eab0: 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
eac0: 68 65 73 20 61 6e 64 20 69 6e 63 6c 75 64 65 73  hes and includes
ead0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
eae0: 6f 6e 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  on how long that
eaf0: 20 73 74 61 74 65 6d 65 6e 74 20 72 61 6e 2e 0a   statement ran..
eb00: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
eb10: 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20  3_profile() API 
eb20: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
eb30: 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
eb40: 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73  ntal and.** is s
eb50: 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
eb60: 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
eb70: 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
eb80: 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
eb90: 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
eba0: 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69  r*), void*);.voi
ebb0: 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
ebc0: 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
ebd0: 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
ebe0: 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
ebf0: 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
ec00: 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
ec10: 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
ec20: 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
ec30: 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  acks.**.** This 
ec40: 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
ec50: 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
ec60: 6e 63 74 69 6f 6e 20 2d 20 74 68 65 20 70 72 6f  nction - the pro
ec70: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d  gress callback -
ec80: 20 74 68 61 74 0a 2a 2a 20 69 73 20 69 6e 76 6f   that.** is invo
ec90: 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
eca0: 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
ecb0: 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ning calls to [s
ecc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 0a  qlite3_exec()],.
ecd0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
ece0: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
ecf0: 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20  _get_table()].  
ed00: 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
ed10: 6f 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74 65  or this .** inte
ed20: 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
ed30: 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
ed40: 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
ed50: 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ery..**.** The p
ed60: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
ed70: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
ed80: 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72   for every N vir
ed90: 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 6f 70 63  tual machine opc
eda0: 6f 64 65 73 2c 0a 2a 2a 20 77 68 65 72 65 20 4e  odes,.** where N
edb0: 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
edc0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
edd0: 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 70 72  function. The pr
ede0: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a  ogress callback.
edf0: 2a 2a 20 69 74 73 65 6c 66 20 69 73 20 69 64 65  ** itself is ide
ee00: 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74  ntified by the t
ee10: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
ee20: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
ee30: 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 61 72  The fourth.** ar
ee40: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66  gument to this f
ee50: 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 76 6f 69  unction is a voi
ee60: 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  d pointer passed
ee70: 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73   to the progress
ee80: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
ee90: 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20  ction each time 
eea0: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  it is invoked..*
eeb0: 2a 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 20 74  *.** If a call t
eec0: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
eed0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
eee0: 70 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  p()], or [sqlite
eef0: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a  3_get_table()].*
ef00: 2a 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77  * results in few
ef10: 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65  er than N opcode
ef20: 73 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  s being executed
ef30: 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  , then the progr
ef40: 65 73 73 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  ess .** callback
ef50: 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65   is never invoke
ef60: 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e 6c 79 20 61  d..** .** Only a
ef70: 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
ef80: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
ef90: 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
efa0: 65 72 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ered for each.**
efb0: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 63   open database c
efc0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 45 76 65 72  onnection.  Ever
efd0: 79 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  y call to sqlite
efe0: 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
eff0: 65 72 28 29 0a 2a 2a 20 6f 76 65 72 77 72 69 74  er().** overwrit
f000: 65 73 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f  es the results o
f010: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
f020: 61 6c 6c 2e 0a 2a 2a 20 54 6f 20 72 65 6d 6f 76  all..** To remov
f030: 65 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  e the progress c
f040: 61 6c 6c 62 61 63 6b 20 61 6c 74 6f 67 65 74 68  allback altogeth
f050: 65 72 2c 20 70 61 73 73 20 4e 55 4c 4c 20 61 73  er, pass NULL as
f060: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
f070: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66  gument to this f
f080: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
f090: 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
f0a0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
f0b0: 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74  a result other t
f0c0: 68 61 6e 20 30 2c 20 74 68 65 6e 20 74 68 65 20  han 0, then the 
f0d0: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 71 75 65 72  current .** quer
f0e0: 79 20 69 73 20 69 6d 6d 65 64 69 61 74 65 6c 79  y is immediately
f0f0: 20 74 65 72 6d 69 6e 61 74 65 64 20 61 6e 64 20   terminated and 
f100: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 68 61  any database cha
f110: 6e 67 65 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b  nges rolled back
f120: 2e 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 61 69 6e  ..** The contain
f130: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
f140: 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
f150: 74 65 70 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  tep()], or.** [s
f160: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
f170: 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
f180: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50   SQLITE_INTERRUP
f190: 54 2e 20 20 20 54 68 69 73 20 66 65 61 74 75 72  T.   This featur
f1a0: 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
f1b0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
f1c0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  o implement the 
f1d0: 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
f1e0: 6f 6e 20 61 0a 2a 2a 20 70 72 6f 67 72 65 73 73  on a.** progress
f1f0: 20 64 69 61 6c 6f 67 20 62 6f 78 20 69 6e 20 61   dialog box in a
f200: 20 47 55 49 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71   GUI..*/.void sq
f210: 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
f220: 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
f230: 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
f240: 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
f250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
f260: 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
f270: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
f280: 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 74 68 65 20 73  **.** Open the s
f290: 71 6c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  qlite database f
f2a0: 69 6c 65 20 22 66 69 6c 65 6e 61 6d 65 22 2e 20  ile "filename". 
f2b0: 20 54 68 65 20 22 66 69 6c 65 6e 61 6d 65 22 20   The "filename" 
f2c0: 69 73 20 55 54 46 2d 38 0a 2a 2a 20 65 6e 63 6f  is UTF-8.** enco
f2d0: 64 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  ded for [sqlite3
f2e0: 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71  _open()] and [sq
f2f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
f300: 20 61 6e 64 20 55 54 46 2d 31 36 20 65 6e 63 6f   and UTF-16 enco
f310: 64 65 64 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ded.** in the na
f320: 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
f330: 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
f340: 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41 6e 20 5b 73  n16()]..** An [s
f350: 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20  qlite3*] handle 
f360: 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  is returned in *
f370: 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66  ppDb, even.** if
f380: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
f390: 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
f3a0: 65 20 69 73 20 6f 70 65 6e 65 64 20 28 6f 72 20  e is opened (or 
f3b0: 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
f3c0: 66 75 6c 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20 5b  fully,.** then [
f3d0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
f3e0: 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73  turned. Otherwis
f3f0: 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  e an error code 
f400: 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65  is returned. The
f410: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
f420: 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
f430: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 20  e3_errmsg16()]  
f440: 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
f450: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
f460: 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
f470: 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
f480: 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a  n of the error..
f490: 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
f4a0: 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
f4b0: 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
f4c0: 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
f4d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
f4e0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
f4f0: 6e 5f 76 32 28 29 5d 20 69 73 20 63 61 6c 6c 65  n_v2()] is calle
f500: 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
f510: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
f520: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2e 0a 2a  16()] is used..*
f530: 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
f540: 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
f550: 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
f560: 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
f570: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
f580: 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
f590: 2a 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  *] handle should
f5a0: 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20   be released by 
f5b0: 70 61 73 73 69 6e 67 20 69 74 20 74 6f 0a 2a 2a  passing it to.**
f5c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
f5d0: 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
f5e0: 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
f5f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ..**.** The [sql
f600: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
f610: 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
f620: 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70  like [sqlite3_op
f630: 65 6e 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  en()] except tha
f640: 74 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 74 77  t.** provides tw
f650: 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
f660: 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
f670: 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 20 6f  tional control o
f680: 76 65 72 20 74 68 65 0a 2a 2a 20 6e 65 77 20 64  ver the.** new d
f690: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f6a0: 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70  on.  The flags p
f6b0: 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
f6c0: 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  one of:.**.** <o
f6d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
f6e0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
f6f0: 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  Y].** <li>  [SQL
f700: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
f710: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  TE].** <li>  [SQ
f720: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
f730: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
f740: 50 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20 3c  PEN_CREATE].** <
f750: 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  /ol>.**.** The f
f760: 69 72 73 74 20 76 61 6c 75 65 20 6f 70 65 6e 73  irst value opens
f770: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 72 65   the database re
f780: 61 64 2d 6f 6e 6c 79 2e 20 20 49 66 20 74 68 65  ad-only.  If the
f790: 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 0a 2a   database does.*
f7a0: 2a 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79  * not previously
f7b0: 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
f7c0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
f7d0: 68 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e  he second option
f7e0: 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61   opens.** the da
f7f0: 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
f800: 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
f810: 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
f820: 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a  eading only if.*
f830: 2a 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  * if the file is
f840: 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
f850: 2e 20 20 49 6e 20 65 69 74 68 65 72 20 63 61 73  .  In either cas
f860: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
f870: 75 73 74 20 61 6c 72 65 61 64 79 0a 2a 2a 20 65  ust already.** e
f880: 78 69 73 74 20 6f 72 20 61 6e 20 65 72 72 6f 72  xist or an error
f890: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
f8a0: 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 20  he third option 
f8b0: 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61  opens the databa
f8c0: 73 65 0a 2a 2a 20 66 6f 72 20 72 65 61 64 69 6e  se.** for readin
f8d0: 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e  g and writing an
f8e0: 64 20 63 72 65 61 74 65 73 20 69 74 20 69 66 20  d creates it if 
f8f0: 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
f900: 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54 68  ady exist..** Th
f910: 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73 20  e third options 
f920: 69 73 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  is behavior that
f930: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
f940: 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
f950: 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
f960: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
f970: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
f980: 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
f990: 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69  y:", then an pri
f9a0: 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f 72  vate.** in-memor
f9b0: 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72  y database is cr
f9c0: 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
f9d0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nnection.  This 
f9e0: 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61 74  in-memory.** dat
f9f0: 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
fa00: 68 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  h when the datab
fa10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
fa20: 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
fa30: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
fa40: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61 6b  SQLite might mak
fa50: 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
fa60: 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
fa70: 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62 65  names.** that be
fa80: 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
fa90: 20 63 68 61 72 61 63 74 65 72 2e 20 20 49 74 20   character.  It 
faa0: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
fab0: 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20 64  hat .** when a d
fac0: 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
fad0: 20 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65 67   really does beg
fae0: 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20 74  in with.** ":" t
faf0: 68 61 74 20 79 6f 75 20 70 72 65 66 69 78 20 74  hat you prefix t
fb00: 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
fb10: 20 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b 65   a pathname like
fb20: 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f 69   "./" to.** avoi
fb30: 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
fb40: 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  ** If the filena
fb50: 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
fb60: 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
fb70: 69 76 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a  ivate temporary.
fb80: 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
fb90: 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
fba0: 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 61  ted.  This priva
fbb0: 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
fbc0: 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
fbd0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
fbe0: 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
fbf0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
fc00: 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
fc10: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
fc20: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
fc30: 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
fc40: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
fc50: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
fc60: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
fc70: 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
fc80: 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74 65   system .** inte
fc90: 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20 6e  rface that the n
fca0: 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
fcb0: 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
fcc0: 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  e.  If the.** fo
fcd0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
fce0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
fcf0: 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
fd00: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a  t [sqlite3_vfs].
fd10: 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  ** object is use
fd20: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
fd30: 20 74 6f 20 77 69 6e 64 6f 77 73 20 75 73 65 72   to windows user
fd40: 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
fd50: 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
fd60: 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
fd70: 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69 74  ent.** of [sqlit
fd80: 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b  e3_open()] and [
fd90: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
fda0: 29 5d 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  )] must be UTF-8
fdb0: 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
fdc0: 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
fdd0: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
fde0: 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
fdf0: 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
fe00: 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
fe10: 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
fe20: 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
fe30: 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
fe40: 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  hem into.** [sql
fe50: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
fe60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
fe70: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
fe80: 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
fe90: 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
fea0: 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
feb0: 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
fec0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
fed0: 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
fee0: 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
fef0: 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
ff00: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
ff10: 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
ff20: 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
ff30: 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
ff40: 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
ff50: 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
ff60: 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
ff70: 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
ff80: 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
ff90: 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
ffa0: 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
ffb0: 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
ffc0: 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
ffd0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
ffe0: 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
fff0: 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
10000 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
10010 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
10020 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
10030 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
10040 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
10050 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
10060 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
10070 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
10080 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
10090 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ssages.**.** The
100a0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
100b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
100c0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
100d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  .** [SQLITE_OK |
100e0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72   result code] or
100f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
10100 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
10110 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66  esult code].** f
10120 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
10130 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
10140 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
10150 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
10160 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65  [sqlite3] handle
10170 20 27 64 62 27 2e 20 20 49 66 20 61 20 70 72 69   'db'.  If a pri
10180 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
10190 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f  ed but the.** mo
101a0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
101b0 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
101c0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
101d0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
101e0 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65  ode().** is unde
101f0 66 69 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  fined. .**.** Th
10200 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
10210 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
10220 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
10230 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 61 75 67   English-langaug
10240 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
10250 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
10260 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
10270 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70  F8 or UTF16 resp
10280 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d  ectively..** Mem
10290 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
102a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
102b0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
102c0 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 20 54 68 65  internally.  The
102d0 20 0a 2a 2a 20 73 74 72 69 6e 67 20 6d 61 79 20   .** string may 
102e0 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
102f0 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
10300 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
10310 73 20 74 6f 20 53 51 4c 69 74 65 0a 2a 2a 20 69  s to SQLite.** i
10320 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
10330 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 73 20  ns..**.** Calls 
10340 74 6f 20 6d 61 6e 79 20 73 71 6c 69 74 65 33 5f  to many sqlite3_
10350 2a 20 66 75 6e 63 74 69 6f 6e 73 20 73 65 74 20  * functions set 
10360 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61  the error code a
10370 6e 64 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  nd string return
10380 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
10390 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
103a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
103b0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
103c0 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 28 6f  rrmsg16()].** (o
103d0 76 65 72 77 72 69 74 69 6e 67 20 74 68 65 20 70  verwriting the p
103e0 72 65 76 69 6f 75 73 20 76 61 6c 75 65 73 29 2e  revious values).
103f0 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 73   Note that calls
10400 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
10410 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  code()],.** [sql
10420 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
10430 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
10440 6d 73 67 31 36 28 29 5d 20 74 68 65 6d 73 65 6c  msg16()] themsel
10450 76 65 73 20 64 6f 20 6e 6f 74 20 61 66 66 65 63  ves do not affec
10460 74 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 73  t the.** results
10470 20 6f 66 20 66 75 74 75 72 65 20 69 6e 76 6f 63   of future invoc
10480 61 74 69 6f 6e 73 2e 20 20 43 61 6c 6c 73 20 74  ations.  Calls t
10490 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74  o API routines t
104a0 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72  hat do not retur
104b0 6e 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f  n.** an error co
104c0 64 65 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71  de (example: [sq
104d0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
104e0 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 63  ()]) do not.** c
104f0 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20  hange the error 
10500 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62 79  code returned by
10510 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20   this routine.  
10520 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20  Interfaces that 
10530 61 72 65 0a 2a 2a 20 6e 6f 74 20 61 73 73 6f 63  are.** not assoc
10540 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65  iated with a spe
10550 63 69 66 69 63 20 64 61 74 61 62 61 73 65 20 63  cific database c
10560 6f 6e 6e 65 63 74 69 6f 6e 20 28 65 78 61 6d 70  onnection (examp
10570 6c 65 73 3a 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  les:.** [sqlite3
10580 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b  _mprintf()] or [
10590 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
105a0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 20 64  hared_cache()] d
105b0 6f 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20  o not change.** 
105c0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e  the return code.
105d0 20 20 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e    .**.** Assumin
105e0 67 20 6e 6f 20 6f 74 68 65 72 20 69 6e 74 65 72  g no other inter
105f0 76 65 6e 69 6e 67 20 73 71 6c 69 74 65 33 5f 2a  vening sqlite3_*
10600 20 41 50 49 20 63 61 6c 6c 73 20 61 72 65 20 6d   API calls are m
10610 61 64 65 2c 20 74 68 65 20 65 72 72 6f 72 0a 2a  ade, the error.*
10620 2a 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20  * code returned 
10630 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
10640 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
10650 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 72 72  ith the same err
10660 6f 72 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 72  or as.** the str
10670 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
10680 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
10690 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
106a0 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f  _errmsg16()]..*/
106b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
106c0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
106d0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
106e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
106f0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
10700 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
10710 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
10720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10730 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
10740 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 49 6e 73  Object.**.** Ins
10750 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
10760 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 20 73  ject represent s
10770 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
10780 65 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a 20 69  ents.  This.** i
10790 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
107a0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
107b0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
107c0 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53   .** "compiled S
107d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
107e0 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
107f0 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a  atement"..** .**
10800 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
10810 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
10820 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
10830 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
10840 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
10850 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
10860 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
10870 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
10880 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
10890 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
108a0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
108b0 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
108c0 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  s using.**      
108d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
108e0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
108f0 64 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d 2e  d_* interfaces].
10900 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
10910 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
10920 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
10930 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
10940 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
10950 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
10960 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
10970 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
10980 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
10990 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
109a0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
109b0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
109c0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
109d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
109e0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
109f0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
10a00 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
10a10 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
10a20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
10a30 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
10a40 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
10a50 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
10a60 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
10a70 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
10a80 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
10a90 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
10aa0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  ement.**.** To e
10ab0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
10ac0 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
10ad0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
10ae0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
10af0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
10b00 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
10b10 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 54  utines. .**.** T
10b20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10b30 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b 73 71  t "db" is an [sq
10b40 6c 69 74 65 33 20 7c 20 53 51 4c 69 74 65 20 64  lite3 | SQLite d
10b50 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d 20  atabase handle] 
10b60 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
10b70 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  m a prior call t
10b80 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
10b90 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
10ba0 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  n_v2()].** or [s
10bb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
10bc0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
10bd0 61 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20  argument "zSql" 
10be0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
10bf0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
10c00 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
10c10 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
10c20 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
10c30 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
10c40 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
10c50 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
10c60 61 63 65 73 20 75 73 65 73 20 55 54 46 2d 38 20  aces uses UTF-8 
10c70 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
10c80 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
10c90 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
10ca0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
10cb0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e  ..**.** If the n
10cc0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
10cd0 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65   less.** than ze
10ce0 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
10cf0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20   read up to the 
10d00 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
10d10 6e 61 74 6f 72 2e 20 20 49 66 0a 2a 2a 20 6e 42  nator.  If.** nB
10d20 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
10d30 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
10d40 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
10d50 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20  er of .** bytes 
10d60 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
10d70 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e   When nByte is n
10d80 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
10d90 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
10da0 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
10db0 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
10dc0 63 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a  character or .**
10dd0 20 75 6e 74 69 6c 20 74 68 65 20 6e 42 79 74 65   until the nByte
10de0 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
10df0 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
10e00 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69  .**.** *pzTail i
10e10 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
10e20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
10e30 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  e past the end o
10e40 66 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 53  f the first.** S
10e50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
10e60 7a 53 71 6c 2e 20 20 54 68 69 73 20 72 6f 75 74  zSql.  This rout
10e70 69 6e 65 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65  ine only compile
10e80 73 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  s the first stat
10e90 65 6d 65 6e 74 0a 2a 2a 20 69 6e 20 7a 53 71 6c  ement.** in zSql
10ea0 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
10eb0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
10ec0 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
10ed0 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
10ee0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
10ef0 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
10f00 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c 69  mpiled .** [sqli
10f10 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73  te3_stmt | SQL s
10f20 74 61 74 65 6d 65 6e 74 20 73 74 72 75 63 74 75  tatement structu
10f30 72 65 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  re] that can be.
10f40 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
10f50 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
10f60 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72 65  )].  Or if there
10f70 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
10f80 70 53 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a 20  pStmt may be.** 
10f90 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66  set to NULL.  If
10fa0 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
10fb0 63 6f 6e 74 61 69 6e 65 64 20 6e 6f 20 53 51 4c  contained no SQL
10fc0 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
10fd0 73 20 61 6e 64 0a 2a 2a 20 65 6d 70 74 79 20 73  s and.** empty s
10fe0 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
10ff0 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
11000 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
11010 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a    The calling.**
11020 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
11030 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
11040 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
11050 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
11060 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  t.** using [sqli
11070 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
11080 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
11090 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
110a0 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
110b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
110c0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
110d0 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c  wise an .** [SQL
110e0 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f  ITE_ERROR | erro
110f0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
11100 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
11110 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
11120 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
11130 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
11140 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
11150 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
11160 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
11170 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
11180 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
11190 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
111a0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
111b0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
111c0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
111d0 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65  raged..** In the
111e0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
111f0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
11200 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
11210 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
11220 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
11230 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
11240 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
11250 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
11260 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
11270 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
11280 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
11290 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61  e to.** behave a
112a0 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
112b0 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  two ways:.**.** 
112c0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
112d0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
112e0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
112f0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
11300 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
11310 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
11320 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
11330 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
11340 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
11350 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
11360 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
11370 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
11380 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66  un it again.  If
11390 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20   the schema has 
113a0 63 68 61 6e 67 65 64 20 69 6e 20 61 20 77 61 79  changed in a way
113b0 0a 2a 2a 20 74 68 61 74 20 6d 61 6b 65 73 20 74  .** that makes t
113c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20  he statement no 
113d0 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73  longer valid, [s
113e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
113f0 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74  ill still.** ret
11400 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  urn [SQLITE_SCHE
11410 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65  MA].  But unlike
11420 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
11430 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43  vior, [SQLITE_SC
11440 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20  HEMA] is.** now 
11450 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20  a fatal error.  
11460 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
11470 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
11480 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61  gain will not ma
11490 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  ke the.** error 
114a0 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20  go away.  Note: 
114b0 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  use [sqlite3_err
114c0 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74  msg()] to find t
114d0 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 70  he text of the p
114e0 61 72 73 69 6e 67 0a 2a 2a 20 65 72 72 6f 72 20  arsing.** error 
114f0 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20  that results in 
11500 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  an [SQLITE_SCHEM
11510 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f  A] return..** </
11520 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
11530 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20  * When an error 
11540 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c  occurs, .** [sql
11550 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
11560 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
11570 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a  the detailed .**
11580 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c   [SQLITE_ERROR |
11590 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f   result codes] o
115a0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
115b0 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
115c0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
115d0 20 73 75 63 68 20 61 73 20 64 69 72 65 63 74 6c   such as directl
115e0 79 2e 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 79  y..** The legacy
115f0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
11600 61 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  at [sqlite3_step
11610 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
11620 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 0a  eturn a generic.
11630 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
11640 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6e  ] result code an
11650 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65  d you would have
11660 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
11670 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  d call to.** [sq
11680 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69  lite3_reset()] i
11690 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
116a0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
116b0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
116c0 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  lem..** With the
116d0 20 22 76 32 22 20 70 72 65 70 61 72 65 20 69 6e   "v2" prepare in
116e0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
116f0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
11700 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
11710 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d  .** returned imm
11720 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
11730 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
11740 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
11750 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
11760 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
11770 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
11780 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
11790 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
117a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
117b0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
117c0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
117d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
117e0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
117f0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
11800 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
11810 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
11820 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
11830 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
11840 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
11850 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
11860 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
11870 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
11880 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
11890 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
118a0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
118b0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
118c0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
118d0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
118e0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
118f0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
11900 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
11910 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
11920 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
11930 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
11940 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
11950 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
11960 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
11970 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
11980 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
11990 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
119a0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
119b0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
119c0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
119d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
119e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
119f0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
11a00 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
11a10 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
11a20 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
11a30 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
11a40 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
11a50 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
11a60 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
11a70 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
11a80 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
11a90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
11aa0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
11ab0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
11ac0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
11ad0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
11ae0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
11af0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
11b00 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
11b10 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
11b20 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
11b30 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
11b40 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
11b50 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
11b60 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
11b70 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
11b80 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
11b90 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
11ba0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
11bb0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
11bc0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
11bd0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
11be0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
11bf0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
11c00 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
11c10 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
11c20 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
11c30 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
11c40 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
11c50 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
11c60 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69 63  PI3REF:  Dynamic
11c70 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
11c80 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 53 51   Object.**.** SQ
11c90 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
11ca0 63 20 74 79 70 69 6e 67 20 66 6f 72 20 74 68 65  c typing for the
11cb0 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
11cc0 73 2e 20 20 56 61 6c 75 65 73 20 63 61 6e 20 0a  s.  Values can .
11cd0 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  ** be integers, 
11ce0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
11cf0 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
11d00 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 20  BLOBs, or NULL. 
11d10 20 57 68 65 6e 0a 2a 2a 20 70 61 73 73 69 6e 67   When.** passing
11d20 20 61 72 6f 75 6e 64 20 76 61 6c 75 65 73 20 69   around values i
11d30 6e 74 65 72 6e 61 6c 6c 79 2c 20 65 61 63 68 20  nternally, each 
11d40 76 61 6c 75 65 20 69 73 20 72 65 70 72 65 73 65  value is represe
11d50 6e 74 65 64 20 61 73 0a 2a 2a 20 61 6e 20 69 6e  nted as.** an in
11d60 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
11d70 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
11d80 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ct..*/.typedef s
11d90 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
11da0 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
11db0 43 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20 46  CAPI3REF:  SQL F
11dc0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
11dd0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
11de0 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
11df0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
11e00 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
11e10 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
11e20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
11e30 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72  ject.  A pointer
11e40 20 74 6f 20 73 75 63 68 20 61 6e 20 6f 62 6a 65   to such an obje
11e50 63 74 20 69 73 20 74 68 65 0a 2a 2a 20 66 69 72  ct is the.** fir
11e60 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
11e70 75 73 65 72 2d 64 65 66 69 6e 65 64 20 53 51 4c  user-defined SQL
11e80 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74   functions..*/.t
11e90 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
11ea0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
11eb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
11ec0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11ed0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
11ee0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
11ef0 65 6d 65 6e 74 73 0a 2a 2a 0a 2a 2a 20 49 6e 20  ements.**.** In 
11f00 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20  the SQL strings 
11f10 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
11f20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
11f30 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
11f40 2c 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ,.** one or more
11f50 20 6c 69 74 65 72 61 6c 73 20 63 61 6e 20 62 65   literals can be
11f60 20 72 65 70 6c 61 63 65 20 62 79 20 61 20 70 61   replace by a pa
11f70 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f  rameter in one o
11f80 66 20 74 68 65 73 65 0a 2a 2a 20 66 6f 72 6d 73  f these.** forms
11f90 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
11fa0 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
11fb0 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
11fc0 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41 41  AAA.** <li>  @AA
11fd0 41 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  A.** <li>  $VVV.
11fe0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
11ff0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
12000 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76  forms shown abov
12010 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65  e NNN is an inte
12020 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
12030 41 41 41 20 69 73 20 61 6e 20 61 6c 70 68 61 6e  AAA is an alphan
12040 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
12050 72 20 61 6e 64 20 56 56 56 20 69 73 20 61 20 76  r and VVV is a v
12060 61 72 69 61 62 6c 65 20 6e 61 6d 65 20 61 63 63  ariable name acc
12070 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  ording.** to the
12080 20 73 79 6e 74 61 78 20 72 75 6c 65 73 20 6f 66   syntax rules of
12090 20 74 68 65 20 54 43 4c 20 70 72 6f 67 72 61 6d   the TCL program
120a0 6d 69 6e 67 20 6c 61 6e 67 75 61 67 65 2e 0a 2a  ming language..*
120b0 2a 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20  * The values of 
120c0 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73  these parameters
120d0 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
120e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
120f0 6d 65 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  mes").** can be 
12100 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
12110 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
12120 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
12130 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  here..**.** The 
12140 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
12150 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
12160 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
12170 61 6c 77 61 79 73 20 69 73 20 61 20 70 6f 69 6e  always is a poin
12180 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
12190 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
121a0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
121b0 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
121c0 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 69  re_v2()] or.** i
121d0 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 54 68  ts variants.  Th
121e0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
121f0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
12200 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  x of the paramet
12210 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 20 54  er to be set.  T
12220 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
12230 65 72 20 68 61 73 0a 2a 2a 20 61 6e 20 69 6e 64  er has.** an ind
12240 65 78 20 6f 66 20 31 2e 20 57 68 65 6e 20 74 68  ex of 1. When th
12250 65 20 73 61 6d 65 20 6e 61 6d 65 64 20 70 61 72  e same named par
12260 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
12270 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
12280 65 63 6f 6e 64 0a 2a 2a 20 61 6e 64 20 73 75 62  econd.** and sub
12290 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
122a0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
122b0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
122c0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
122d0 63 65 2e 20 20 54 68 65 20 69 6e 64 65 78 20 66  ce.  The index f
122e0 6f 72 0a 2a 2a 20 6e 61 6d 65 64 20 70 61 72 61  or.** named para
122f0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
12300 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
12310 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
12320 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
12330 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  e()] API if desi
12340 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 20  red.  The index 
12350 66 6f 72 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 70 61  for "?NNN".** pa
12360 72 61 6d 65 74 65 73 20 69 73 20 74 68 65 20 76  rametes is the v
12370 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
12380 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
12390 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
123a0 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  and the compile-
123b0 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  time.** paramete
123c0 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52  r SQLITE_MAX_VAR
123d0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65  IABLE_NUMBER (de
123e0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
123f0 29 2e 0a 2a 2a 20 53 65 65 20 3c 61 20 68 72 65  )..** See <a hre
12400 66 3d 22 6c 69 6d 69 74 73 2e 68 74 6d 6c 22 3e  f="limits.html">
12410 6c 69 6d 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e 20  limits.html</a> 
12420 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
12430 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
12440 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
12450 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
12460 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
12470 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
12480 2a 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f  * In those.** ro
12490 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
124a0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
124b0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
124c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
124d0 79 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70  ytes.** in the p
124e0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
124f0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
12500 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  e is the number 
12510 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 0a  of bytes in the.
12520 2a 2a 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  ** string, not t
12530 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
12540 72 61 63 74 65 72 73 2e 20 20 54 68 65 20 6e 75  racters.  The nu
12550 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
12560 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
12570 65 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  e the zero-termi
12580 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
12590 20 6f 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20   of strings..** 
125a0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
125b0 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
125c0 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20  ive, the length 
125d0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
125e0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
125f0 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
12600 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
12610 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  tor..**.** The f
12620 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
12630 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
12640 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
12650 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
12660 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
12670 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
12680 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
12690 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
126a0 4c 4f 42 20 6f 72 0a 2a 2a 20 74 65 78 74 20 61  LOB or.** text a
126b0 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
126c0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
126d0 2e 20 20 49 66 20 74 68 65 20 66 69 66 74 68 20  .  If the fifth 
126e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
126f0 2a 2a 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  ** special value
12700 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
12710 2c 20 74 68 65 6e 20 74 68 65 20 6c 69 62 72 61  , then the libra
12720 72 79 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ry assumes that 
12730 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  the information.
12740 2a 2a 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  ** is in static,
12750 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
12760 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
12770 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 20  ed to be freed. 
12780 20 49 66 20 74 68 65 0a 2a 2a 20 66 69 66 74 68   If the.** fifth
12790 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
127a0 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
127b0 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
127c0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
127d0 73 0a 2a 2a 20 6f 77 6e 20 70 72 69 76 61 74 65  s.** own private
127e0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
127f0 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
12800 65 66 6f 72 65 20 74 68 65 20 73 71 6c 69 74 65  efore the sqlite
12810 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 72 6f  3_bind_*().** ro
12820 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
12830 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12840 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
12850 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
12860 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
12870 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  n that.** is fil
12880 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e 20  led with zeros. 
12890 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73   A zeroblob uses
128a0 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
128b0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
128c0 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
128d0 20 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 77   hold it size) w
128e0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
128f0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
12900 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
12910 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
12920 73 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20  s place-holders 
12930 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
12940 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
12950 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
12960 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  g .** [sqlite3_b
12970 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
12980 6d 65 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ment BLOB I/O] r
12990 6f 75 74 69 6e 65 73 2e 20 20 41 20 6e 65 67 61  outines.  A nega
129a0 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65 20 66 6f  tive.** value fo
129b0 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
129c0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
129d0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
129e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
129f0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
12a00 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
12a10 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74   after.** [sqlit
12a20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
12a30 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e   (and its varian
12a40 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ts) or [sqlite3_
12a50 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20  reset()] and.** 
12a60 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
12a70 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64  step()]..** Bind
12a80 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
12a90 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
12aa0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
12ab0 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e  utine..** Unboun
12ac0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
12ad0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
12ae0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  NULL..**.** Thes
12af0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
12b00 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
12b10 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65   success or an e
12b20 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20  rror code if.** 
12b30 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
12b40 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41  ong.  [SQLITE_RA
12b50 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
12b60 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
12b70 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
12b80 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51  t of range.  [SQ
12b90 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
12ba0 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
12bb0 63 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c  c fails..** [SQL
12bc0 49 54 45 5f 4d 49 53 55 53 45 5d 20 69 73 20 72  ITE_MISUSE] is r
12bd0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65  eturned if these
12be0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
12bf0 6c 6c 65 64 20 6f 6e 20 61 20 76 69 72 74 75 61  lled on a virtua
12c00 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 74 68 61  l.** machine tha
12c10 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73  t is the wrong s
12c20 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61  tate or which ha
12c30 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66  s already been f
12c40 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f 0a 69 6e 74  inalized..*/.int
12c50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
12c60 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
12c70 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
12c80 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
12c90 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
12ca0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
12cb0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
12cc0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
12cd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
12ce0 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
12cf0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
12d00 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
12d10 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
12d20 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
12d30 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
12d40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
12d50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
12d60 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
12d70 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
12d80 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
12d90 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
12da0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
12db0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
12dc0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
12dd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
12de0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
12df0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
12e00 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
12e10 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
12e20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
12e30 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
12e40 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
12e50 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
12e60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
12e70 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
12e80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
12e90 62 65 72 20 4f 66 20 48 6f 73 74 20 50 61 72 61  ber Of Host Para
12ea0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 52 65 74  meters.**.** Ret
12eb0 75 72 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20  urn the largest 
12ec0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  host parameter i
12ed0 6e 64 65 78 20 69 6e 20 74 68 65 20 70 72 65 63  ndex in the prec
12ee0 6f 6d 70 69 6c 65 64 20 73 74 61 74 65 6d 65 6e  ompiled statemen
12ef0 74 20 67 69 76 65 6e 0a 2a 2a 20 61 73 20 74 68  t given.** as th
12f00 65 20 61 72 67 75 6d 65 6e 74 2e 20 20 57 68 65  e argument.  Whe
12f10 6e 20 74 68 65 20 68 6f 73 74 20 70 61 72 61 6d  n the host param
12f20 65 74 65 72 73 20 61 72 65 20 6f 66 20 74 68 65  eters are of the
12f30 20 66 6f 72 6d 73 20 6c 69 6b 65 20 22 3a 41 41   forms like ":AA
12f40 41 22 0a 2a 2a 20 6f 72 20 22 3f 22 2c 20 74 68  A".** or "?", th
12f50 65 6e 20 74 68 65 79 20 61 72 65 20 61 73 73 69  en they are assi
12f60 67 6e 65 64 20 73 65 71 75 65 6e 74 69 61 6c 20  gned sequential 
12f70 69 6e 63 72 65 61 73 69 6e 67 20 6e 75 6d 62 65  increasing numbe
12f80 72 73 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  rs beginning.** 
12f90 77 69 74 68 20 6f 6e 65 2c 20 73 6f 20 74 68 65  with one, so the
12fa0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
12fb0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
12fc0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 48 6f   parameters.  Ho
12fd0 77 65 76 65 72 0a 2a 2a 20 69 66 20 74 68 65 20  wever.** if the 
12fe0 73 61 6d 65 20 68 6f 73 74 20 70 61 72 61 6d 65  same host parame
12ff0 74 65 72 20 6e 61 6d 65 20 69 73 20 75 73 65 64  ter name is used
13000 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 2c   multiple times,
13010 20 65 61 63 68 20 6f 63 63 75 72 72 61 6e 63 65   each occurrance
13020 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20 74 68 65  .** is given the
13030 20 73 61 6d 65 20 6e 75 6d 62 65 72 2c 20 73 6f   same number, so
13040 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
13050 6e 65 64 20 69 6e 20 74 68 61 74 20 63 61 73 65  ned in that case
13060 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a   is the number.*
13070 2a 20 6f 66 20 75 6e 69 71 75 65 20 68 6f 73 74  * of unique host
13080 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
13090 2e 20 20 49 66 20 68 6f 73 74 20 70 61 72 61 6d  .  If host param
130a0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
130b0 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 61 72 65 20  m "?NNN".** are 
130c0 75 73 65 64 20 28 77 68 65 72 65 20 4e 4e 4e 20  used (where NNN 
130d0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 20 74  is an integer) t
130e0 68 65 6e 20 74 68 65 72 65 20 6d 69 67 68 74 20  hen there might 
130f0 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 0a 2a  be gaps in the.*
13100 2a 20 6e 75 6d 62 65 72 69 6e 67 20 61 6e 64 20  * numbering and 
13110 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
13120 65 64 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  ed by this inter
13130 66 61 63 65 20 69 73 20 74 68 65 20 69 6e 64 65  face is the inde
13140 78 20 6f 66 20 74 68 65 0a 2a 2a 20 68 6f 73 74  x of the.** host
13150 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
13160 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65  the largest inde
13170 78 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  x value..**.** T
13180 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
13190 65 6d 65 6e 74 20 6d 75 73 74 20 6e 6f 74 20 62  ement must not b
131a0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  e [sqlite3_final
131b0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
131c0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 69  .** prior to thi
131d0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
131e0 6e 69 6e 67 2e 20 20 4f 74 68 65 72 77 69 73 65  ning.  Otherwise
131f0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
13200 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 61 6e   undefined.** an
13210 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
13220 69 72 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73  irable..*/.int s
13230 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
13240 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
13250 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
13260 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
13270 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
13280 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 54 68 69 73  meter.**.** This
13290 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
132a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
132b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d  e name of the n-
132c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  th parameter in 
132d0 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  a .** [sqlite3_s
132e0 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73  tmt | prepared s
132f0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 48 6f  tatement]..** Ho
13300 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  st parameters of
13310 20 74 68 65 20 66 6f 72 6d 20 22 3a 41 41 41 22   the form ":AAA"
13320 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
13330 56 56 56 22 20 68 61 76 65 20 61 20 6e 61 6d 65  VVV" have a name
13340 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 74 68 65  .** which is the
13350 20 73 74 72 69 6e 67 20 22 3a 41 41 41 22 20 6f   string ":AAA" o
13360 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 56 56  r "@AAA" or "$VV
13370 56 22 2e 20 20 0a 2a 2a 20 49 6e 20 6f 74 68 65  V".  .** In othe
13380 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
13390 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
133a0 6f 72 20 22 40 22 0a 2a 2a 20 69 73 20 69 6e 63  or "@".** is inc
133b0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
133c0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61   the name..** Pa
133d0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
133e0 66 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e  form "?" or "?NN
133f0 4e 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e  N" have no name.
13400 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
13410 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72   bound parameter
13420 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
13430 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
13440 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20   If the value n 
13450 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
13460 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70  or if the n-th p
13470 61 72 61 6d 65 74 65 72 20 69 73 20 6e 61 6d 65  arameter is name
13480 6c 65 73 73 2c 0a 2a 2a 20 74 68 65 6e 20 4e 55  less,.** then NU
13490 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
134a0 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
134b0 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 69  ring is always i
134c0 6e 20 74 68 65 0a 2a 2a 20 55 54 46 2d 38 20 65  n the.** UTF-8 e
134d0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
134e0 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
134f0 74 65 72 20 77 61 73 20 6f 72 69 67 69 6e 61 6c  ter was original
13500 6c 79 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ly specified.** 
13510 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
13520 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
13530 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
13540 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
13550 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
13560 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
13570 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
13580 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
13590 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
135a0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
135b0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
135c0 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 54 68  en Name.**.** Th
135d0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
135e0 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
135f0 61 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  a host parameter
13600 20 77 69 74 68 20 74 68 65 20 67 69 76 65 6e 20   with the given 
13610 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d  name..** The nam
13620 65 20 6d 75 73 74 20 6d 61 74 63 68 20 65 78 61  e must match exa
13630 63 74 6c 79 2e 20 20 49 66 20 6e 6f 20 70 61 72  ctly.  If no par
13640 61 6d 65 74 65 72 20 77 69 74 68 20 74 68 65 20  ameter with the 
13650 67 69 76 65 6e 20 6e 61 6d 65 20 69 73 20 0a 2a  given name is .*
13660 2a 20 66 6f 75 6e 64 2c 20 72 65 74 75 72 6e 20  * found, return 
13670 30 2e 20 20 50 61 72 61 6d 65 74 65 72 20 6e 61  0.  Parameter na
13680 6d 65 73 20 6d 75 73 74 20 62 65 20 55 54 46 38  mes must be UTF8
13690 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
136a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
136b0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
136c0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
136d0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
136e0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
136f0 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
13700 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
13710 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72  ment.**.** Contr
13720 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
13730 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
13740 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
13750 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65  does not.** rese
13760 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  t the [sqlite3_b
13770 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
13780 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 73  ngs] on a .** [s
13790 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72  qlite3_stmt | pr
137a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
137b0 5d 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f 75  ].  Use this rou
137c0 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74  tine to.** reset
137d0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
137e0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
137f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
13800 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
13810 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
13820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
13830 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
13840 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
13850 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
13860 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
13870 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
13880 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
13890 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
138a0 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
138b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e   SQL statement].
138c0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
138d0 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53  turns 0.** if pS
138e0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74  tmt is an SQL st
138f0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
13900 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
13910 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70  a (for .** examp
13920 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a  le an UPDATE)..*
13930 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
13940 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
13950 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
13960 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13970 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
13980 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
13990 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
139a0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
139b0 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
139c0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
139d0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
139e0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45  sult set of a SE
139f0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20  LECT statement. 
13a00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
13a10 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
13a20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
13a30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55  a pointer to a U
13a40 54 46 38 20 73 74 72 69 6e 67 20 61 6e 64 20 73  TF8 string and s
13a50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
13a60 6d 65 31 36 28 29 0a 2a 2a 20 72 65 74 75 72 6e  me16().** return
13a70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13a80 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20   UTF16 string.  
13a90 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
13aa0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 73  ter is the.** [s
13ab0 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72  qlite3_stmt | pr
13ac0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
13ad0 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  ] that implement
13ae0 73 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61  s the SELECT sta
13af0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73  tement..** The s
13b00 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
13b10 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75  is the column nu
13b20 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 2d  mber.  The left-
13b30 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a  most column is.*
13b40 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  * number 0..**.*
13b50 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
13b60 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
13b70 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
13b80 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  her the .** [sql
13b90 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
13ba0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
13bb0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
13bc0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
13bd0 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c  e()].** or until
13be0 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73   the next call s
13bf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
13c00 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
13c10 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a  column_name16().
13c20 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  ** on the same c
13c30 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  olumn..**.** If 
13c40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13c50 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
13c60 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
13c70 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
13c80 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
13c90 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
13ca0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
13cb0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
13cc0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
13cd0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a  is returned..*/.
13ce0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
13cf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
13d00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
13d10 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
13d20 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
13d30 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
13d40 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
13d50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13d60 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
13d70 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
13d80 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  t.**.** These ro
13d90 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
13da0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
13db0 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20  ine what column 
13dc0 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65  of what.** table
13dd0 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61   in which databa
13de0 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  se a result of a
13df0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
13e00 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a  t comes from..**
13e10 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
13e20 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
13e30 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
13e40 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
13e50 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 38  ** either a UTF8
13e60 20 6f 72 20 55 54 46 31 36 20 73 74 72 69 6e 67   or UTF16 string
13e70 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65  .  The _database
13e80 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
13e90 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
13ea0 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
13eb0 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
13ec0 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
13ed0 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
13ee0 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
13ef0 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
13f00 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72  n name..** The r
13f10 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
13f20 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a  s valid until.**
13f30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
13f40 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
13f50 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
13f60 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  royed using.** [
13f70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
13f80 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
13f90 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
13fa0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
13fb0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
13fc0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
13fd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73  .**.** The names
13fe0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
13ff0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
14000 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
14010 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
14020 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
14030 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  n..**.** The fir
14040 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
14050 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c  he following cal
14060 6c 73 20 69 73 20 61 20 0a 2a 2a 20 5b 73 71 6c  ls is a .** [sql
14070 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70  ite3_stmt | comp
14080 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
14090 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75  nt]..** These fu
140a0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
140b0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
140c0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
140d0 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20  returned by .** 
140e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
140f0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
14100 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
14110 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  gument..**.** If
14120 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
14130 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
14140 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
14150 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72  expression.** or
14160 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
14170 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
14180 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
14190 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
141a0 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  .** return NULL.
141b0 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79   Otherwise, they
141c0 20 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20   return the .** 
141d0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
141e0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
141f0 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
14200 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
14210 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20  t.** column was 
14220 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
14230 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c  **.** As with al
14240 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
14250 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66  PIs, those postf
14260 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72  ixed with "16" r
14270 65 74 75 72 6e 20 55 54 46 2d 31 36 0a 2a 2a 20  eturn UTF-16.** 
14280 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c  encoded strings,
14290 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
142a0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
142b0 38 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41  8..**.** These A
142c0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
142d0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
142e0 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
142f0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
14300 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
14310 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72  LUMN_METADATA pr
14320 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
14330 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  l defined..**.**
14340 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
14350 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
14360 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
14370 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
14380 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
14390 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
143a0 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
143b0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
143c0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
143d0 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
143e0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
143f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
14400 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
14410 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
14420 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
14430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
14440 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
14450 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
14460 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
14470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
14480 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
14490 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
144a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
144b0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
144c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
144d0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
144e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
144f0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
14500 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
14510 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
14520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
14530 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
14540 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
14550 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
14560 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
14570 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
14580 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  lt.**.** The fir
14590 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
145a0 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  a [sqlite3_stmt 
145b0 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  | compiled SQL s
145c0 74 61 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 49  tatement]. .** I
145d0 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
145e0 20 69 73 20 61 20 53 45 4c 45 43 54 20 73 74 61   is a SELECT sta
145f0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
14600 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
14610 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65   .** returned re
14620 73 75 6c 74 20 73 65 74 20 20 6f 66 20 74 68 61  sult set  of tha
14630 74 20 53 45 4c 45 43 54 20 69 73 20 61 20 74 61  t SELECT is a ta
14640 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
14650 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
14660 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
14670 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
14680 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
14690 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
146a0 65 74 75 72 6e 65 64 2e 20 49 66 20 74 68 65 20  eturned. If the 
146b0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
146c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
146d0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
146e0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
146f0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
14700 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
14710 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
14720 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
14730 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 46  UTF-8 encoded. F
14740 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 0a 2a  or example, in.*
14750 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  * the database s
14760 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
14770 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
14780 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
14790 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  And the followin
147a0 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  g statement comp
147b0 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
147c0 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
147d0 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65  OM t1;.**.** The
147e0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
147f0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
14800 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
14810 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 0a   for the second.
14820 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ** result column
14830 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
14840 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
14850 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
14860 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30   column.** (i==0
14870 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  )..**.** SQLite 
14880 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
14890 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53  -time typing.  S
148a0 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
148b0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
148c0 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
148d0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
148e0 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
148f0 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
14900 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
14910 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
14920 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
14930 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
14940 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
14950 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
14960 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
14970 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69  atic.  Type.** i
14980 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
14990 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
149a0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
149b0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
149c0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
149d0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
149e0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
149f0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
14a00 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
14a10 2c 20 69 6e 74 20 69 29 3b 0a 63 6f 6e 73 74 20  , int i);.const 
14a20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
14a30 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
14a40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
14a50 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49  t);../* .** CAPI
14a60 33 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65 20  3REF:  Evaluate 
14a70 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
14a80 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e 20  .**.** After an 
14a90 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
14aa0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  SQL statement] h
14ab0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
14ac0 20 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a 20   with a call.** 
14ad0 74 6f 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  to either [sqlit
14ae0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
14af0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
14b00 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
14b10 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  to one of.** the
14b20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
14b30 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
14b40 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
14b50 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
14b60 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 66 75  .** then this fu
14b70 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 63  nction must be c
14b80 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
14b90 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
14ba0 61 74 65 20 74 68 65 20 0a 2a 2a 20 73 74 61 74  ate the .** stat
14bb0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
14bc0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
14bd0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
14be0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
14bf0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
14c00 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
14c10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
14c20 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
14c30 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
14c40 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
14c50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
14c60 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
14c70 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
14c80 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
14c90 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
14ca0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
14cb0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
14cc0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
14cd0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
14ce0 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
14cf0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
14d00 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
14d10 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
14d20 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
14d30 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
14d40 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
14d50 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ted..**.** In th
14d60 65 20 6c 61 67 61 63 79 20 69 6e 74 65 72 66 61  e lagacy interfa
14d70 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
14d80 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
14d90 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
14da0 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ], .** [SQLITE_D
14db0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
14dc0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
14dd0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
14de0 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20  ISUSE]..** With 
14df0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
14e00 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
14e10 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  ther [SQLITE_OK 
14e20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a  | result code].*
14e30 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
14e40 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
14e50 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
14e60 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
14e70 64 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a  d as.** well..**
14e80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
14e90 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
14ea0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
14eb0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
14ec0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
14ed0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
14ee0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
14ef0 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61  job.  If the sta
14f00 74 65 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d  tement is a COMM
14f10 49 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  IT.** or occurs 
14f20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
14f30 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
14f40 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
14f50 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
14f60 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
14f70 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
14f80 74 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f  t a COMMIT and o
14f90 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
14fa0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
14fb0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
14fc0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
14fd0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
14fe0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
14ff0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  uing..**.** [SQL
15000 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
15010 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
15020 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
15030 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
15040 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
15050 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
15060 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
15070 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
15080 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
15090 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
150a0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
150b0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
150c0 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
150d0 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
150e0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
150f0 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  te..**.** If the
15100 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
15110 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
15120 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
15130 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  then .** [SQLITE
15140 5f 52 4f 57 5d 20 69 73 20 72 65 74 75 72 6e 65  _ROW] is returne
15150 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
15160 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
15170 20 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72   ready.** for pr
15180 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 20  ocessing by the 
15190 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
151a0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
151b0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  ed using.** the 
151c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
151d0 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 63  int | column acc
151e0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
151f0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
15200 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
15210 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
15220 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
15230 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49  ta..** .** [SQLI
15240 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
15250 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
15260 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
15270 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
15280 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
15290 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
152a0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
152b0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
152c0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
152d0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
152e0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
152f0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
15300 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
15310 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79   With the legacy
15320 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
15330 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
15340 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a  r code (example:
15350 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
15360 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
15370 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
15380 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
15390 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
153a0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
153b0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
153c0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
153d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
153e0 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
153f0 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20  ement].  In the 
15400 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
15410 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
15420 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
15430 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
15440 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
15450 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
15460 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
15470 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
15480 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
15490 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
154a0 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
154b0 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
154c0 6e 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  n a [sqlite3_stm
154d0 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
154e0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
154f0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
15500 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
15510 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
15520 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
15530 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ad .** previousl
15540 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
15550 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
15560 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
15570 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
15580 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
15590 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
155a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
155b0 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
155c0 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
155d0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
155e0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
155f0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
15600 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
15610 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61  >.** In the lega
15620 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 0a 2a  cy interface, .*
15630 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  * the sqlite3_st
15640 65 70 28 29 20 41 50 49 20 61 6c 77 61 79 73 20  ep() API always 
15650 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
15660 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a  c error code,.**
15670 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
15680 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 65   following any e
15690 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
156a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
156b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
156c0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
156d0 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 65  call [sqlite3_re
156e0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
156f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
15700 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
15710 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70  nd one of the sp
15720 65 63 69 66 69 63 0a 2a 2a 20 5b 53 51 4c 49 54  ecific.** [SQLIT
15730 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74  E_ERROR | result
15740 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
15750 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
15760 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
15770 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
15780 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
15790 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
157a0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
157b0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
157c0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
157d0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
157e0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
157f0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
15800 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
15810 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
15820 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
15830 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
15840 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
15850 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15860 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
15870 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
15880 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f 72  then the .** mor
15890 65 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49  e specific [SQLI
158a0 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c  TE_ERROR | resul
158b0 74 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  t codes] are ret
158c0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
158d0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
158e0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
158f0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
15900 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
15910 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
15920 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
15930 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
15940 41 50 49 33 52 45 46 3a 0a 2a 2a 0a 2a 2a 20 52  API3REF:.**.** R
15950 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
15960 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68   of values in th
15970 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
15980 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e   the result set.
15990 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 63  .**.** After a c
159a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
159b0 73 74 65 70 28 29 5d 20 74 68 61 74 20 72 65 74  step()] that ret
159c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57  urns [SQLITE_ROW
159d0 5d 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  ], this routine.
159e0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74  ** will return t
159f0 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 61 73  he same value as
15a00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
15a10 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 20 66 75  lumn_count()] fu
15a20 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41 66 74 65 72  nction..** After
15a30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
15a40 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61  ] has returned a
15a50 6e 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  n [SQLITE_DONE],
15a60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
15a70 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c 49 54 45 5f  or.** a [SQLITE_
15a80 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f  ERROR | error co
15a90 64 65 5d 2c 20 6f 72 20 62 65 66 6f 72 65 20 5b  de], or before [
15aa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
15ab0 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 63 61 6c  has been .** cal
15ac0 6c 65 64 20 6f 6e 20 74 68 65 20 5b 73 71 6c 69  led on the [sqli
15ad0 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61  te3_stmt | prepa
15ae0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66  red statement] f
15af0 6f 72 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  or the first tim
15b00 65 2c 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  e,.** this routi
15b10 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  ne returns zero.
15b20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
15b30 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
15b40 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
15b50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15b60 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
15b70 74 61 74 79 70 65 73 0a 2a 2a 0a 2a 2a 20 45 76  tatypes.**.** Ev
15b80 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
15b90 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
15ba0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
15bb0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
15bc0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
15bd0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
15be0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
15bf0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
15c00 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
15c10 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
15c20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
15c30 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 0a  > NULL.** </ul>.
15c40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
15c50 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
15c60 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
15c70 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
15c80 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
15c90 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
15ca0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
15cb0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
15cc0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
15cd0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
15ce0 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
15cf0 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
15d00 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
15d10 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
15d20 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
15d30 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
15d40 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f   SQLITE3_TEXT no
15d50 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
15d60 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
15d70 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
15d80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
15d90 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
15da0 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
15db0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
15dc0 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
15dd0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
15de0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
15df0 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
15e00 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
15e10 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
15e20 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
15e30 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
15e40 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20  PI3REF: Results 
15e50 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
15e60 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ery.**.** These 
15e70 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
15e80 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
15e90 74 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63 6f  t.** a single co
15ea0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
15eb0 65 6e 74 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  ent result row o
15ec0 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65  f a query.  In e
15ed0 76 65 72 79 0a 2a 2a 20 63 61 73 65 20 74 68 65  very.** case the
15ee0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15ef0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15f00 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
15f10 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61 74  _stmt | SQL stat
15f20 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
15f30 65 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65  eing.** evaluate
15f40 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
15f50 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 61 73 20  stmt*] that was 
15f60 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a  returned from .*
15f70 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
15f80 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
15f90 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
15fa0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f   and.** the seco
15fb0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
15fc0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
15fd0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
15fe0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a   information .**
15ff0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
16000 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d  ned.  The left-m
16010 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
16020 65 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20  e result set.** 
16030 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
16040 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
16050 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
16060 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
16070 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
16080 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
16090 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64  * the column ind
160a0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
160b0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
160c0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a  s undefined. .**
160d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
160e0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
160f0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
16100 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
16110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
16120 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
16130 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
16140 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
16150 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
16160 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
16170 6c 69 7a 65 28 29 5d 20 68 61 73 20 62 65 65 6e  lize()] has been
16180 20 63 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74   call subsequent
16190 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
161a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
161b0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
161c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
161d0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
161e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
161f0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
16200 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
16210 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
16220 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
16230 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
16240 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
16250 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
16260 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
16270 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
16280 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
16290 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
162a0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
162b0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
162c0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
162d0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
162e0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
162f0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
16300 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a   undefined.  .**
16310 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
16320 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
16330 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a  utine returns .*
16340 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
16350 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
16360 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
16370 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
16380 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
16390 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72  lumn.  The retur
163a0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
163b0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
163c0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
163d0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
163e0 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
163f0 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
16400 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
16410 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
16420 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
16430 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
16440 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
16450 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
16460 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
16470 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
16480 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
16490 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
164a0 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
164b0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
164c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
164d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
164e0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
164f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
16500 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
16510 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
16520 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
16530 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
16540 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
16550 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
16560 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
16570 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
16580 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
16590 75 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20  umn_bytes() .** 
165a0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
165b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
165c0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
165d0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49   or string..** I
165e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
165f0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
16600 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
16610 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
16620 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
16630 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
16640 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
16650 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
16660 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  s..** If the res
16670 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
16680 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
16690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
166a0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
166b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
166c0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
166d0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
166e0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
166f0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
16700 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
16710 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68  at string..** Th
16720 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
16730 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
16740 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
16750 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
16760 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
16770 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a  g.  For clarity:
16780 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
16790 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
167a0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
167b0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
167c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
167d0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
167e0 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   Strings returne
167f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
16800 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
16810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
16820 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
16830 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 73 74 72 69  zero-length stri
16840 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
16850 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
16860 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20    The return.** 
16870 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
16880 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
16890 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
168a0 74 68 20 62 6c 6f 62 20 69 73 20 61 6e 20 61 72  th blob is an ar
168b0 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74  bitrary.** point
168c0 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65  er, possibly eve
168d0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
168e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
168f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
16900 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  16() routine is 
16910 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74  similar to sqlit
16920 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
16930 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20  ).** but leaves 
16940 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54  the result in UT
16950 46 2d 31 36 20 69 6e 73 74 65 61 64 20 6f 66 20  F-16 instead of 
16960 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20  UTF-8.  .** The 
16970 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
16980 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
16990 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
169a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
169b0 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
169c0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
169d0 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
169e0 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  te.  For.** exam
169f0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
16a00 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
16a10 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
16a20 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
16a30 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
16a40 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
16a50 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
16a60 65 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20 74 68  ernally to do th
16a70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20  e conversion.** 
16a80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
16a90 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
16aa0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
16ab0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68 61 74  conversions that
16ac0 0a 2a 2a 20 61 72 65 20 61 70 70 6c 69 65 64 3a  .** are applied:
16ad0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
16ae0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
16af0 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
16b00 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
16b10 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
16b20 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
16b30 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
16b40 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
16b50 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
16b60 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
16b70 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
16b80 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
16b90 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
16ba0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
16bb0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
16bc0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
16bd0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
16be0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
16bf0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
16c00 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
16c10 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
16c20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
16c30 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
16c40 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
16c50 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
16c60 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
16c70 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
16c80 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
16c90 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
16ca0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
16cb0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
16cc0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
16cd0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
16ce0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f   <td> Same as fo
16cf0 72 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  r INTEGER->TEXT.
16d00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
16d10 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
16d20 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
16d30 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
16d40 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
16d50 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
16d60 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
16d70 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
16d80 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
16d90 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
16da0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
16db0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
16dc0 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
16dd0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
16de0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
16df0 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
16e00 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
16e10 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
16e20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
16e30 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
16e40 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
16e50 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
16e60 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
16e70 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
16e80 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
16e90 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
16ea0 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
16eb0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
16ec0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
16ed0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
16ee0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
16ef0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
16f00 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
16f10 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
16f20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
16f30 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
16f40 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
16f50 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
16f60 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
16f70 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
16f80 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
16f90 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
16fa0 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
16fb0 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
16fc0 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
16fd0 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
16fe0 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
16ff0 73 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65  s.** on equavale
17000 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
17010 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
17020 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
17030 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
17040 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
17050 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
17060 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
17070 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
17080 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
17090 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
170a0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
170b0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
170c0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
170d0 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
170e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
170f0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
17100 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
17110 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
17120 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
17130 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
17140 69 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65  idated. .** Type
17150 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
17160 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
17170 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
17180 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
17190 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
171a0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
171b0 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c  <p>  The initial
171c0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
171d0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
171e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a  olumn_text() .**
171f0 20 20 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c            or sql
17200 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
17210 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
17220 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
17230 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
17240 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
17250 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
17260 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a  ing.</p></li>.**
17270 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
17280 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
17290 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
172a0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
172b0 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
172c0 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74  *          sqlit
172d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
172e0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
172f0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
17300 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
17310 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d           to UTF-
17320 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a  16.</p></li>.**.
17330 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20  ** <li><p>  The 
17340 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
17350 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
17360 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
17370 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
17380 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
17390 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
173a0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
173b0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
173c0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
173d0 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
173e0 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  p></li>.** </ul>
173f0 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f  .**.** Conversio
17400 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
17410 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
17420 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
17430 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
17440 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
17450 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
17460 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
17470 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
17480 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
17490 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
174a0 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20   pointer points 
174b0 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  to will have bee
174c0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
174d0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
174e0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
174f0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
17500 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
17510 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74   but sometime it
17520 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69   is.** not possi
17530 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
17540 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
17550 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
17560 64 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  dated.  .**.** T
17570 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
17580 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
17590 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
175a0 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
175b0 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
175c0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
175d0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c  ways:.**.**  <ul
175e0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
175f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
17600 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
17610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
17620 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
17630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
17640 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
17650 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
17660 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
17670 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
17680 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
17690 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
176a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
176b0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c  ()</li>.**  </ul
176c0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
176d0 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
176e0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
176f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73  column_text(), s
17700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
17710 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69  ob(),.** or sqli
17720 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
17730 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
17740 63 65 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  ce the result in
17750 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a  to the desired.*
17760 2a 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  * format, then i
17770 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
17780 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20  lumn_bytes() or 
17790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
177a0 79 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66  ytes16() to.** f
177b0 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
177c0 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
177d0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20  not mix call to 
177e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
177f0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ext() or.** sqli
17800 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
17810 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  ) with calls to 
17820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
17830 79 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64  ytes16().  And d
17840 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c  o not.** mix cal
17850 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
17860 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69  lumn_text16() wi
17870 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
17880 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
17890 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  ()..**.** The po
178a0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
178b0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
178c0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
178d0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
178e0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
178f0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
17900 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
17910 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
17920 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
17930 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
17940 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  led.  The memory
17950 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
17960 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
17970 6e 64 20 62 6c 6f 62 73 20 69 73 20 66 72 65 65  nd blobs is free
17980 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
17990 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
179a0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
179b0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
179c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
179d0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
179e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
179f0 65 74 63 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73  etc. into .** [s
17a00 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
17a10 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72  **.** If a memor
17a20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
17a30 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
17a40 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
17a50 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
17a60 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
17a70 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
17a80 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
17a90 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
17aa0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
17ab0 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
17ac0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
17ad0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
17ae0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
17af0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
17b00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
17b10 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
17b20 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
17b30 4d 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  MEM]..*/.const v
17b40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
17b50 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
17b60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
17b70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
17b80 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
17b90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
17ba0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
17bb0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
17bc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
17bd0 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
17be0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
17bf0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
17c00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
17c10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
17c20 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
17c30 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
17c40 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
17c50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
17c60 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
17c70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
17c80 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
17c90 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
17ca0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
17cb0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
17cc0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
17cd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
17ce0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
17cf0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
17d00 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
17d10 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
17d20 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
17d30 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
17d40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
17d50 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
17d60 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
17d70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17d80 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
17d90 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
17da0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ect.**.** The sq
17db0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
17dc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
17dd0 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
17de0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
17df0 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  t | compiled SQL
17e00 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20   statement]. If 
17e10 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
17e20 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73 75  s.** executed su
17e30 63 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e  ccessfully, or n
17e40 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61  ot executed at a
17e50 6c 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ll, then SQLITE_
17e60 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  OK is returned..
17e70 2a 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20  ** If execution 
17e80 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
17e90 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20   failed then an 
17ea0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
17eb0 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  R | error code] 
17ec0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
17ed0 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
17ee0 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20   error code].** 
17ef0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a  is returned. .**
17f00 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
17f10 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
17f20 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
17f30 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
17f40 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
17f50 74 65 33 5f 73 74 6d 74 20 7c 20 76 69 72 74 75  te3_stmt | virtu
17f60 61 6c 20 6d 61 63 68 69 6e 65 5d 2e 20 20 49 66  al machine].  If
17f70 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63   the virtual mac
17f80 68 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  hine has not .**
17f90 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
17fa0 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72  tion when this r
17fb0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
17fc0 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a  , that is like.*
17fd0 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61  * encountering a
17fe0 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e  n error or an in
17ff0 74 65 72 72 75 70 74 2e 20 20 28 53 65 65 20 5b  terrupt.  (See [
18000 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18010 74 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d  t()].) .** Incom
18020 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
18030 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
18040 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
18050 73 20 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a  s cancelled,  .*
18060 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
18070 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
18080 2c 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 53  , and the .** [S
18090 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65  QLITE_ERROR | re
180a0 73 75 6c 74 20 63 6f 64 65 5d 20 72 65 74 75 72  sult code] retur
180b0 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c  ned will be [SQL
180c0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69  ITE_ABORT]..*/.i
180d0 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
180e0 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
180f0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
18100 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
18110 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
18120 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
18130 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
18140 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
18150 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
18160 65 74 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  et a .** [sqlite
18170 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65  3_stmt | compile
18180 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d  d SQL statement]
18190 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b   object..** back
181a0 20 74 6f 20 69 74 27 73 20 69 6e 69 74 69 61 6c   to it's initial
181b0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
181c0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
181d0 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74  .** Any SQL stat
181e0 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
181f0 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
18200 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
18210 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
18220 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
18230 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
18240 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
18250 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
18260 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
18270 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
18280 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
18290 67 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  gs..*/.int sqlit
182a0 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
182b0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
182c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
182d0 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
182e0 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
182f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
18300 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
18310 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
18320 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
18330 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a   or aggregates.*
18340 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  * or to redefine
18350 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
18360 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
18370 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
18380 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64  gates.  The.** d
18390 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62  ifference only b
183a0 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69  etween the two i
183b0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
183c0 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  d parameter, the
183d0 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
183e0 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f  (scalar) functio
183f0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
18400 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  is encoded in UT
18410 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
18420 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
18430 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20  on() and UTF-16 
18440 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
18450 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e  te_function16().
18460 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
18470 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
18480 20 5b 73 71 6c 69 74 65 33 20 7c 20 64 61 74 61   [sqlite3 | data
18490 62 61 73 65 20 68 61 6e 64 6c 65 5d 20 74 68 61  base handle] tha
184a0 74 20 68 6f 6c 64 73 20 74 68 65 0a 2a 2a 20 53  t holds the.** S
184b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
184c0 67 67 72 65 67 61 74 65 20 69 73 20 74 6f 20 62  ggregate is to b
184d0 65 20 61 64 64 65 64 20 6f 72 20 72 65 64 65 66  e added or redef
184e0 69 6e 65 64 2e 20 49 66 20 61 20 73 69 6e 67 6c  ined. If a singl
184f0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
18500 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
18510 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
18520 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e  internally, then
18530 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
18540 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
18550 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e  must be added in
18560 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65 61  dividually to ea
18570 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68  ch database.** h
18580 61 6e 64 6c 65 20 77 69 74 68 20 77 68 69 63 68  andle with which
18590 20 74 68 65 79 20 77 69 6c 6c 20 62 65 20 75 73   they will be us
185a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
185b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
185c0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
185d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
185e0 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20  o be created.** 
185f0 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a  or redefined..**
18600 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   The length of t
18610 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
18620 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c  ed to 255 bytes,
18630 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
18640 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69  e .** zero-termi
18650 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61  nator.  Note tha
18660 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74  t the name lengt
18670 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79  h limit is in by
18680 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72  tes, not.** char
18690 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74  acters.  Any att
186a0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
186b0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
186c0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
186d0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61  will result in a
186e0 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65  n SQLITE_ERROR e
186f0 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rror..**.** The 
18700 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
18710 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
18720 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
18730 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
18740 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
18750 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20   takes. If this 
18760 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
18770 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
18780 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
18790 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
187a0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
187b0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a   of arguments..*
187c0 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
187d0 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
187e0 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
187f0 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  hat .** [SQLITE_
18800 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
18810 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
18820 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
18830 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
18840 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20  eters.  Any SQL 
18850 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
18860 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  ntation should b
18870 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
18880 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d  * work with UTF-
18890 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
188a0 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
188b0 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
188c0 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
188d0 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
188e0 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
188f0 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74  han another.  It
18900 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a   is allowed to.*
18910 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
18920 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
18930 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
18940 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
18950 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
18960 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
18970 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
18980 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
18990 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
189a0 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70  ..** When multip
189b0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
189c0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
189d0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
189e0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
189f0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
18a00 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
18a10 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
18a20 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
18a30 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
18a40 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
18a50 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
18a60 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
18a70 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65   care what.** te
18a80 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  xt encoding is u
18a90 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
18aa0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
18ab0 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49  ould be.** [SQLI
18ac0 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54  TE_ANY]..**.** T
18ad0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
18ae0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
18af0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
18b00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
18b10 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ** of the functi
18b20 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
18b30 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
18b40 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  er using.** [sql
18b50 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
18b60 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76  ]..**.** The sev
18b70 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64  enth, eighth and
18b80 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
18b90 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
18ba0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
18bb0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
18bc0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
18bd0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
18be0 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  nt the SQL.** fu
18bf0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
18c00 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51  ate. A scalar SQ
18c10 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
18c20 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
18c30 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20  ation of.** the 
18c40 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f  xFunc callback o
18c50 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly, NULL pointe
18c60 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  rs should be pas
18c70 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
18c80 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70  .** and xFinal p
18c90 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67  arameters. An ag
18ca0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
18cb0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
18cc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
18cd0 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20  ** of xStep and 
18ce0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
18cf0 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
18d00 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64   for xFunc. To d
18d10 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73  elete an.** exis
18d20 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
18d30 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
18d40 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c  pass NULL for al
18d50 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
18d60 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  .** callback..**
18d70 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74  .** It is permit
18d80 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
18d90 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
18da0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
18db0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
18dc0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
18dd0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
18de0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
18df0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
18e00 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
18e10 69 6e 67 20 70 65 72 66 65 72 72 65 64 20 74 65  ing perferred te
18e20 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53  xt encodings.  S
18e30 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
18e40 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
18e50 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  tion most closel
18e60 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
18e70 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
18e80 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
18e90 73 20 75 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  s used..*/.int s
18ea0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
18eb0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
18ec0 33 20 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  3 *,.  const cha
18ed0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
18ee0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
18ef0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
18f00 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a  void*,.  void (*
18f10 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
18f20 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
18f30 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
18f40 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
18f50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
18f60 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
18f70 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
18f80 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
18f90 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
18fa0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
18fb0 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
18fc0 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 76 6f  te3*,.  const vo
18fd0 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
18fe0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
18ff0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
19000 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28   void*,.  void (
19010 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
19020 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
19030 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
19040 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
19050 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
19060 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
19070 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
19080 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
19090 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a  ontext*).);../*.
190a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
190b0 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
190c0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
190d0 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
190e0 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
190f0 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
19100 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
19110 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
19120 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
19130 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
19140 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
19150 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
19160 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
19170 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
19180 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
19190 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
191a0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
191b0 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
191c0 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
191d0 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
191e0 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
191f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
19200 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
19210 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
19220 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
19230 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
19240 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
19250 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
19260 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65  PI3REF: Obsolete
19270 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
19280 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
19290 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73   are all now obs
192a0 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72  olete.  In order
192b0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
192c0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
192d0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
192e0 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74  er code, we cont
192f0 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a  inue to support.
19300 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ** these functio
19310 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ns.  However, ne
19320 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72  w development pr
19330 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76  ojects should av
19340 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
19350 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
19360 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
19370 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
19380 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
19390 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
193a0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
193b0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e   to tell you wan
193c0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e  t they do..*/.in
193d0 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
193e0 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
193f0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74  3_context*);.int
19400 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
19410 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
19420 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61  .int sqlite3_tra
19430 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
19440 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
19450 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e  lite3_stmt*);.in
19460 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
19470 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
19480 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
19490 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
194a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
194b0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
194c0 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
194d0 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a  eter Values.**.*
194e0 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
194f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
19500 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
19510 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
19520 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
19530 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
19540 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
19550 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
19560 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
19570 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
19580 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
19590 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
195a0 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
195b0 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
195c0 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
195d0 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
195e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
195f0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
19600 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
19610 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
19620 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
19630 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
19640 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
19650 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
19660 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
19670 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
19680 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
19690 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
196a0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
196b0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
196c0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
196d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
196e0 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
196f0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
19700 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
19710 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
19720 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
19730 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
19740 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
19750 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
19760 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
19770 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
19780 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
19790 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
197a0 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  lumn_blob | sqli
197b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75  te3_column_* rou
197c0 74 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74 68  tines] except th
197d0 61 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  at .** these rou
197e0 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
197f0 67 6c 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  gle [sqlite3_val
19800 75 65 2a 5d 20 70 6f 69 6e 74 65 72 20 69 6e 73  ue*] pointer ins
19810 74 65 61 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  tead.** of an [s
19820 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
19830 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
19840 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
19850 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
19860 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
19870 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
19880 78 74 72 61 63 74 73 20 61 20 55 54 46 31 36 20  xtracts a UTF16 
19890 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
198a0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
198b0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
198c0 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20  achine.  The.** 
198d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
198e0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
198f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
19900 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
19910 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 31  .** extract UTF1
19920 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
19930 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
19940 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
19950 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  tively..**.** Th
19960 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
19970 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
19980 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
19990 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
199a0 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
199b0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
199c0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
199d0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
199e0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
199f0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
19a00 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
19a10 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
19a20 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
19a30 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
19a40 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
19a50 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
19a60 72 64 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66  rder.** words if
19a70 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 6f 72   the value is or
19a80 69 67 69 6e 61 6c 20 61 20 73 74 72 69 6e 67 20  iginal a string 
19a90 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
19aa0 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
19ab0 6e 20 69 74 20 69 73 20 64 6f 6e 65 2e 20 20 4f  n it is done.  O
19ac0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
19ad0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20  ersion occurs.  
19ae0 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  The .** [SQLITE_
19af0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
19b00 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
19b10 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
19b20 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
19b30 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
19b40 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
19b50 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
19b60 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  nter that.** is 
19b70 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
19b80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
19b90 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
19ba0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
19bb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
19bc0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
19bd0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
19be0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
19bf0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
19c00 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
19c10 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
19c20 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
19c30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
19c40 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
19c50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
19c60 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  16()].  .**.** T
19c70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
19c80 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
19c90 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
19ca0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
19cb0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
19cc0 70 70 6c 69 65 64 20 74 68 65 20 73 71 6c 69 74  pplied the sqlit
19cd0 65 33 5f 76 61 6c 75 65 2a 20 70 61 72 61 6d 65  e3_value* parame
19ce0 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c 20 69 66 20  ters..** Or, if 
19cf0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
19d00 65 2a 20 61 72 67 75 6d 65 6e 74 20 63 6f 6d 65  e* argument come
19d10 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
19d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
19d30 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
19d40 2c 20 74 68 65 6e 20 74 68 65 73 65 20 72 6f 75  , then these rou
19d50 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 20  tines should be 
19d60 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
19d70 73 61 6d 65 20 74 68 72 65 61 64 0a 2a 2a 20 74  same thread.** t
19d80 68 61 74 20 72 61 6e 20 5b 73 71 6c 69 74 65 33  hat ran [sqlite3
19d90 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
19da0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
19db0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
19dc0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
19dd0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
19de0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
19df0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
19e00 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
19e10 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
19e20 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
19e30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
19e40 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
19e50 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
19e60 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
19e70 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
19e80 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
19e90 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
19ea0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
19eb0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
19ec0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
19ed0 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
19ee0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
19ef0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
19f00 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
19f10 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
19f20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
19f30 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
19f40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
19f50 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
19f60 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
19f70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
19f80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
19f90 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
19fa0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
19fb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
19fc0 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
19fd0 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
19fe0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
19ff0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
1a000 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
1a010 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
1a020 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67  tation of aggreg
1a030 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
1a040 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  s use this routi
1a050 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a  ne to allocate.*
1a060 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f  * a structure fo
1a070 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
1a080 73 74 61 74 65 2e 20 20 54 68 65 20 66 69 72 73  state.  The firs
1a090 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74  t time this rout
1a0a0 69 6e 65 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64  ine.** is called
1a0b0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1a0c0 72 20 61 67 67 72 65 67 61 74 65 2c 20 61 20 6e  r aggregate, a n
1a0d0 65 77 20 73 74 72 75 63 74 75 72 65 20 6f 66 20  ew structure of 
1a0e0 73 69 7a 65 20 6e 42 79 74 65 73 0a 2a 2a 20 69  size nBytes.** i
1a0f0 73 20 61 6c 6c 6f 63 61 74 65 64 2c 20 7a 65 72  s allocated, zer
1a100 6f 65 64 2c 20 61 6e 64 20 72 65 74 75 72 6e 65  oed, and returne
1a110 64 2e 20 20 4f 6e 20 73 75 62 73 65 71 75 65 6e  d.  On subsequen
1a120 74 20 63 61 6c 6c 73 20 28 66 6f 72 20 74 68 65  t calls (for the
1a130 0a 2a 2a 20 73 61 6d 65 20 61 67 67 72 65 67 61  .** same aggrega
1a140 74 65 20 69 6e 73 74 61 6e 63 65 29 20 74 68 65  te instance) the
1a150 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
1a160 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 69  returned.  The i
1a170 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
1a180 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
1a190 65 20 63 61 6e 20 75 73 65 20 74 68 65 20 72 65  e can use the re
1a1a0 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f  turned buffer to
1a1b0 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61   accumulate data
1a1c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 66 66  ..**.** The buff
1a1d0 65 72 20 61 6c 6c 6f 63 61 74 65 64 20 69 73 20  er allocated is 
1a1e0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
1a1f0 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 77 68  lly by SQLite wh
1a200 61 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  an the aggregate
1a210 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  .** query conclu
1a220 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
1a230 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73  irst parameter s
1a240 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20  hould be a copy 
1a250 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  of the .** [sqli
1a260 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
1a270 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
1a280 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
1a290 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1a2a0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1a2b0 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
1a2c0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
1a2d0 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
1a2e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
1a2f0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
1a300 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
1a310 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
1a320 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
1a330 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
1a340 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
1a350 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1a360 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
1a370 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
1a380 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
1a390 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a3a0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
1a3b0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1a3c0 20 54 68 65 20 70 55 73 65 72 44 61 74 61 20 70   The pUserData p
1a3d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a3e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
1a3f0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
1a400 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
1a410 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
1a420 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65   routines.** use
1a430 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 75 73  d to register us
1a440 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 69 73 20  er functions is 
1a450 61 76 61 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a 20  available to.** 
1a460 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1a470 6f 6e 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  on of the functi
1a480 6f 6e 20 75 73 69 6e 67 20 74 68 69 73 20 63 61  on using this ca
1a490 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ll..**.** This r
1a4a0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
1a4b0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
1a4c0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
1a4d0 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
1a4e0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
1a4f0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
1a500 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
1a510 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
1a520 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a530 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
1a540 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
1a550 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
1a560 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
1a570 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
1a580 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
1a590 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
1a5a0 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68 20   meta-data with 
1a5b0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
1a5c0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
1a5d0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
1a5e0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
1a5f0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
1a600 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
1a610 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
1a620 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
1a630 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
1a640 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
1a650 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d 61  ted meta-data ma
1a660 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
1a670 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
1a680 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
1a690 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
1a6a0 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
1a6b0 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
1a6c0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
1a6d0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
1a6e0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
1a6f0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
1a700 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64  red as.** meta-d
1a710 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
1a720 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ith the SQL valu
1a730 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
1a740 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
1a750 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20  on.** pattern.  
1a760 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  The compiled reg
1a770 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
1a780 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
1a790 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
1a7a0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
1a7b0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f  same function so
1a7c0 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e   that the origin
1a7d0 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  al pattern strin
1a7e0 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65  g.** does not ne
1a7f0 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69  ed to be recompi
1a800 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f  led on each invo
1a810 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  cation..**.** Th
1a820 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
1a830 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
1a840 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1a850 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 2d  ter to the meta-
1a860 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
1a870 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  ed with the Nth 
1a880 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 20 74  argument value t
1a890 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 53 51  o the current SQ
1a8a0 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  L function.** ca
1a8b0 6c 6c 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ll, where N is t
1a8c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a8d0 74 65 72 2e 20 49 66 20 6e 6f 20 6d 65 74 61 2d  ter. If no meta-
1a8e0 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 73 65  data has been se
1a8f0 74 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 76 61  t for.** that va
1a900 6c 75 65 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  lue, then a NULL
1a910 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
1a920 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
1a930 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
1a940 61 74 61 28 29 20 69 73 20 75 73 65 64 20 74 6f  ata() is used to
1a950 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d   associate meta-
1a960 64 61 74 61 20 77 69 74 68 20 61 6e 20 53 51 4c  data with an SQL
1a970 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  .** function arg
1a980 75 6d 65 6e 74 2e 20 54 68 65 20 74 68 69 72 64  ument. The third
1a990 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1a9a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
1a9b0 65 74 61 2d 64 61 74 61 0a 2a 2a 20 74 6f 20 62  eta-data.** to b
1a9c0 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
1a9d0 68 20 74 68 65 20 4e 74 68 20 75 73 65 72 20 66  h the Nth user f
1a9e0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
1a9f0 20 76 61 6c 75 65 2e 20 54 68 65 20 66 6f 75 72   value. The four
1aa00 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  th.** parameter 
1aa10 73 70 65 63 69 66 69 65 73 20 61 20 64 65 73 74  specifies a dest
1aa20 72 75 63 74 6f 72 20 74 68 61 74 20 77 69 6c 6c  ructor that will
1aa30 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   be called on th
1aa40 65 20 6d 65 74 61 2d 0a 2a 2a 20 64 61 74 61 20  e meta-.** data 
1aa50 70 6f 69 6e 74 65 72 20 74 6f 20 72 65 6c 65 61  pointer to relea
1aa60 73 65 20 69 74 20 77 68 65 6e 20 69 74 20 69 73  se it when it is
1aa70 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
1aa80 72 65 64 2e 20 49 66 20 74 68 65 20 0a 2a 2a 20  red. If the .** 
1aa90 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 4e 55  destructor is NU
1aaa0 4c 4c 2c 20 69 74 20 69 73 20 6e 6f 74 20 69 6e  LL, it is not in
1aab0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  voked..**.** In 
1aac0 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d 64  practice, meta-d
1aad0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
1aae0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
1aaf0 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
1ab00 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
1ab10 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
1ab20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
1ab30 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
1ab40 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
1ab50 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e  d SQL variables.
1ab60 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1ab70 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
1ab80 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
1ab90 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
1aba0 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
1abb0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
1abc0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
1abd0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
1abe0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1abf0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
1ac00 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
1ac10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1ac20 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 76  *, int, void*, v
1ac30 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
1ac40 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
1ac50 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
1ac60 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
1ac70 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
1ac80 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
1ac90 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
1aca0 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
1acb0 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
1acc0 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
1acd0 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
1ace0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
1acf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
1ad00 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20  lob()].  If the 
1ad10 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
1ad20 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
1ad30 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
1ad40 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
1ad50 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
1ad60 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
1ad70 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
1ad80 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
1ad90 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
1ada0 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c  ed.  The .** SQL
1adb0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
1adc0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
1add0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
1ade0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
1adf0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
1ae00 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
1ae10 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
1ae20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
1ae30 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
1ae40 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
1ae50 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
1ae60 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
1ae70 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
1ae80 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
1ae90 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
1aea0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
1aeb0 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
1aec0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
1aed0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
1aee0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
1aef0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
1af00 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
1af10 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
1af20 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
1af30 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
1af40 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
1af50 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
1af60 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
1af70 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
1af80 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
1af90 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
1afa0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1afb0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
1afc0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
1afd0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
1afe0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
1aff0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
1b000 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
1b010 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
1b020 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
1b030 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
1b040 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
1b050 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
1b060 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
1b070 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
1b080 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
1b090 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a  uch like the .**
1b0a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1b0b0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
1b0c0 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20  nd_*] family of 
1b0d0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a  functions used.*
1b0e0 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  * to bind values
1b0f0 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
1b100 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
1b110 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
1b120 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  efer to the.** [
1b130 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1b140 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
1b150 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  _* documentation
1b160 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  ] for.** additio
1b170 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
1b180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1b190 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
1b1a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
1b1b0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
1b1c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
1b1d0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
1b1e0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
1b1f0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
1b200 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 70 61  tion.  The.** pa
1b210 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1b220 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
1b230 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
1b240 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
1b250 20 69 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   is the text of 
1b260 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1b270 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1b280 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
1b290 67 28 29 20 63 61 75 73 65 20 74 68 65 20 66 75  g() cause the fu
1b2a0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
1b2b0 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 72 6f  ation.** to thro
1b2c0 77 20 61 6e 64 20 65 72 72 6f 72 20 69 6e 64 69  w and error indi
1b2d0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
1b2e0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
1b2f0 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65  to long.** to re
1b300 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  present..**.** T
1b310 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
1b320 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
1b330 6d 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  m within the sam
1b340 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
1b350 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
1b360 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1b370 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
1b380 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2e 0a 2a  text] pointer..*
1b390 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
1b3a0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
1b3b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
1b3c0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
1b3d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1b3e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
1b3f0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
1b400 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
1b410 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
1b420 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
1b430 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1b440 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
1b450 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
1b460 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
1b470 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1b480 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
1b490 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
1b4a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
1b4b0 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
1b4c0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
1b4d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1b4e0 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
1b4f0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
1b500 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1b510 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
1b520 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
1b530 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1b540 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
1b550 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
1b560 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
1b570 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
1b580 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
1b590 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
1b5a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
1b5b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1b5c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
1b5d0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1b5e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1b5f0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
1b600 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1b610 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1b620 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1b630 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1b640 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
1b650 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1b660 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1b670 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
1b680 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1b690 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
1b6a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1b6b0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
1b6c0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
1b6d0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
1b6e0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
1b6f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b700 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
1b710 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1b720 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
1b730 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b740 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
1b750 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
1b760 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
1b770 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54  equences.**.** T
1b780 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
1b790 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e  re used to add n
1b7a0 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
1b7b0 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a  uences to the.**
1b7c0 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64   [sqlite3*] hand
1b7d0 6c 65 20 73 70 65 63 69 66 69 65 64 20 61 73 20  le specified as 
1b7e0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1b7f0 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  nt. .**.** The n
1b800 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63  ame of the new c
1b810 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
1b820 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61  e is specified a
1b830 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
1b840 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
1b850 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1b860 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
1b870 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
1b880 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
1b890 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20  F-16 string for 
1b8a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1b8b0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 20 49  ollation16().  I
1b8c0 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74  n all cases.** t
1b8d0 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65  he name is passe
1b8e0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1b8f0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
1b900 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  t..**.** The thi
1b910 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  rd argument must
1b920 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
1b930 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
1b940 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _UTF8],.** [SQLI
1b950 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b  TE_UTF16LE] or [
1b960 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
1b970 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
1b980 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69   the user-suppli
1b990 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78  ed.** routine ex
1b9a0 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73  pects to be pass
1b9b0 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ed pointers to s
1b9c0 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75  trings encoded u
1b9d0 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55  sing UTF-8,.** U
1b9e0 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
1b9f0 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69  ian or UTF-16 bi
1ba00 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  g-endian respect
1ba10 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 70  ively..**.** A p
1ba20 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73  ointer to the us
1ba30 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74  er supplied rout
1ba40 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73  ine must be pass
1ba50 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a  ed as the fifth.
1ba60 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ** argument. If 
1ba70 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73  it is NULL, this
1ba80 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
1ba90 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c  deleting the col
1baa0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
1bab0 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69  ce (so that SQLi
1bac0 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69  te cannot call i
1bad0 74 20 61 6e 79 6d 6f 72 65 29 2e 20 45 61 63 68  t anymore). Each
1bae0 20 74 69 6d 65 20 74 68 65 20 75 73 65 72 0a 2a   time the user.*
1baf0 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  * supplied funct
1bb00 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
1bb10 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20 63  it is passed a c
1bb20 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1bb30 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
1bb40 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
1bb50 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  t to sqlite3_cre
1bb60 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
1bb70 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  or.** sqlite3_cr
1bb80 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
1bb90 28 29 20 61 73 20 69 74 73 20 66 69 72 73 74 20  () as its first 
1bba0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1bbb0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61   The remaining a
1bbc0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
1bbd0 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20 72 6f  user-supplied ro
1bbe0 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
1bbf0 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
1bc00 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
1bc10 5b 6c 65 6e 67 74 68 2c 20 64 61 74 61 5d 20 70  [length, data] p
1bc20 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
1bc30 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
1bc40 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
1bc50 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
1bc60 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
1bc70 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
1bc80 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
1bc90 73 74 65 72 65 64 2e 20 54 68 65 20 75 73 65 72  stered. The user
1bca0 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
1bcb0 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
1bcc0 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
1bcd0 65 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73  e if.** the firs
1bce0 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
1bcf0 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
1bd00 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
1bd10 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73   the second.** s
1bd20 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52  tring. i.e. (STR
1bd30 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e  ING1 - STRING2).
1bd40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1bd50 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1bd60 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
1bd70 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
1bd80 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
1bd90 2a 20 65 78 63 61 70 74 20 74 68 61 74 20 69 74  * excapt that it
1bda0 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20   takes an extra 
1bdb0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
1bdc0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
1bdd0 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  or.** the collat
1bde0 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75  ion.  The destru
1bdf0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77  ctor is called w
1be00 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
1be10 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65  n is.** destroye
1be20 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20  d and is passed 
1be30 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f  a copy of the fo
1be40 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76  urth parameter v
1be50 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  oid* pointer.** 
1be60 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
1be70 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
1be80 76 32 28 29 2e 20 20 43 6f 6c 6c 61 74 69 6f 6e  v2().  Collation
1be90 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20  s are destroyed 
1bea0 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65  when.** they are
1beb0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
1bec0 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68  ater calls to th
1bed0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
1bee0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  tion functions.*
1bef0 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 73  * or when the [s
1bf00 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73  qlite3*] databas
1bf10 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73  e handle is clos
1bf20 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1bf30 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
1bf40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72  * The sqlite3_cr
1bf50 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
1bf60 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
1bf70 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1bf80 64 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  d.** subject to 
1bf90 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1bfa0 20 72 65 6c 65 61 73 65 73 2e 20 20 54 68 65 20   releases.  The 
1bfb0 6f 74 68 65 72 20 63 6f 6c 6c 61 74 69 6f 6e 20  other collation 
1bfc0 63 72 65 61 74 69 6f 6e 0a 2a 2a 20 66 75 6e 63  creation.** func
1bfd0 74 69 6f 6e 73 20 61 72 65 20 73 74 61 62 6c 65  tions are stable
1bfe0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1bff0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1c000 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
1c010 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
1c020 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
1c030 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
1c040 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
1c050 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1c060 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
1c070 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
1c080 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1c090 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
1c0a0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
1c0b0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
1c0c0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
1c0d0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
1c0e0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
1c0f0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
1c100 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
1c110 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
1c120 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
1c130 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
1c140 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
1c150 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
1c160 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
1c170 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
1c180 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
1c190 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
1c1a0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
1c1b0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
1c1c0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
1c1d0 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
1c1e0 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
1c1f0 73 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  s.**.** To avoid
1c200 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
1c210 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
1c220 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
1c230 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
1c240 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
1c250 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
1c260 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
1c270 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
1c280 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1c290 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 6c  handle to be cal
1c2a0 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  led whenever an 
1c2b0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
1c2c0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a  ion sequence is.
1c2d0 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ** required..**.
1c2e0 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69  ** If the functi
1c2f0 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
1c300 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1c310 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1c320 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
1c330 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
1c340 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
1c350 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
1c360 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
1c370 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
1c380 20 69 6e 20 55 54 46 2d 38 2e 20 49 66 20 73 71   in UTF-8. If sq
1c390 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
1c3a0 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
1c3b0 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a  ed, the names.**
1c3c0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
1c3d0 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
1c3e0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1c3f0 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65 69  er. A call to ei
1c400 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ther.** function
1c410 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78   replaces any ex
1c420 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e  isting callback.
1c430 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1c440 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1c450 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
1c460 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
1c470 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
1c480 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1c490 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
1c4a0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
1c4b0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
1c4c0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
1c4d0 36 28 29 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  6(). The second 
1c4e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1c4f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64  database.** hand
1c500 6c 65 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  le. The third ar
1c510 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
1c520 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
1c530 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
1c540 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
1c550 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
1c560 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
1c570 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
1c580 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
1c590 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
1c5a0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 54 68 65  on required. The
1c5b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1c5c0 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
1c5d0 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
1c5e0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
1c5f0 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  nce..**.** The c
1c600 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1c610 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
1c620 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
1c630 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
1c640 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
1c650 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
1c660 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1c670 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
1c680 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
1c690 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
1c6a0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1c6b0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
1c6c0 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
1c6d0 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
1c6e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
1c6f0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
1c700 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
1c710 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1c720 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
1c730 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
1c740 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
1c750 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
1c760 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
1c770 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
1c780 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
1c790 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
1c7a0 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
1c7b0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
1c7c0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
1c7d0 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
1c7e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
1c7f0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
1c800 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
1c810 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
1c820 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
1c830 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
1c840 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
1c850 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
1c860 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1c870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1c880 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
1c890 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
1c8a0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
1c8b0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
1c8c0 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
1c8d0 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
1c8e0 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
1c8f0 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
1c900 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
1c910 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
1c920 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
1c930 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
1c940 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
1c950 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
1c960 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
1c970 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
1c980 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
1c990 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
1c9a0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
1c9b0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
1c9c0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
1c9d0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
1c9e0 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
1c9f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1ca00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1ca10 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
1ca20 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
1ca30 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
1ca40 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
1ca50 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  new key */.);../
1ca60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1ca70 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
1ca80 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
1ca90 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  me.**.** This fu
1caa0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
1cab0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
1cac0 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
1cad0 75 74 69 6f 6e 0a 2a 2a 20 61 20 6e 75 6d 62 65  ution.** a numbe
1cae0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
1caf0 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
1cb00 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
1cb10 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
1cb20 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
1cb30 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
1cb40 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
1cb50 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64   .** millisecond
1cb60 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
1cb70 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
1cb80 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
1cb90 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65  up to .** the ne
1cba0 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
1cbb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
1cbc0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1cbd0 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72  p actually .** r
1cbe0 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
1cbf0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1cc00 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
1cc10 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
1cc20 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
1cc30 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
1cc40 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
1cc50 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
1cc60 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1cc70 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
1cc80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
1cc90 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
1cca0 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65 20  CAPI3REF:  Name 
1ccb0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
1ccc0 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
1ccd0 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 49 66 20 74  Files.**.** If t
1cce0 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
1ccf0 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
1cd00 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
1cd10 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
1cd20 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
1cd30 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74 6f  r (a.ka. directo
1cd40 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
1cd50 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
1cd60 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
1cd70 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
1cd80 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
1cd90 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
1cda0 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c  riable.** is NUL
1cdb0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
1cdc0 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73 65  SQLite does a se
1cdd0 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
1cde0 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61 72  opriate temporar
1cdf0 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 74  y.** file direct
1ce00 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
1ce10 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64   not safe to mod
1ce20 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
1ce30 65 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61 73  e once a databas
1ce40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1ce50 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  has been opened.
1ce60 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64    It is intended
1ce70 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
1ce80 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
1ce90 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
1cea0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
1ceb0 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
1cec0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
1ced0 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
1cee0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20   have been call 
1cef0 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  and remain uncha
1cf00 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e  nged thereafter.
1cf10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
1cf20 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
1cf30 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
1cf40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cf50 20 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66    Test To See If
1cf60 20 54 68 65 20 44 61 74 61 62 61 73 65 20 49 73   The Database Is
1cf70 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20   In Auto-Commit 
1cf80 4d 6f 64 65 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20  Mode.**.** Test 
1cf90 74 6f 20 73 65 65 20 77 68 65 74 68 65 72 20 6f  to see whether o
1cfa0 72 20 6e 6f 74 20 74 68 65 20 64 61 74 61 62 61  r not the databa
1cfb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1cfc0 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a   in autocommit.*
1cfd0 2a 20 6d 6f 64 65 2e 20 20 52 65 74 75 72 6e 20  * mode.  Return 
1cfe0 54 52 55 45 20 69 66 20 69 74 20 69 73 20 61 6e  TRUE if it is an
1cff0 64 20 46 41 4c 53 45 20 69 66 20 6e 6f 74 2e 20  d FALSE if not. 
1d000 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
1d010 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66   is on.** by def
1d020 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69  ault.  Autocommi
1d030 74 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  t is disabled by
1d040 20 61 20 42 45 47 49 4e 20 73 74 61 74 65 6d 65   a BEGIN stateme
1d050 6e 74 20 61 6e 64 20 72 65 65 6e 61 62 6c 65 64  nt and reenabled
1d060 0a 2a 2a 20 62 79 20 74 68 65 20 6e 65 78 74 20  .** by the next 
1d070 43 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c 42 41  COMMIT or ROLLBA
1d080 43 4b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  CK..**.** If ano
1d090 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e  ther thread chan
1d0a0 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d  ges the autocomm
1d0b0 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65  it status of the
1d0c0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
1d0d0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
1d0e0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
1d0f0 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
1d100 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
1d110 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
1d120 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
1d130 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69  _autocommit(sqli
1d140 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1d150 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54 68  PI3REF:  Find Th
1d160 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
1d170 65 20 41 73 73 6f 63 69 61 74 65 64 20 57 69 74  e Associated Wit
1d180 68 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  h A Prepared Sta
1d190 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52 65 74  tement.**.** Ret
1d1a0 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  urn the [sqlite3
1d1b0 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  *] database hand
1d1c0 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a  le to which a.**
1d1d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
1d1e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1d1f0 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a  ent] belongs..**
1d200 20 54 68 69 73 20 69 73 20 74 68 65 20 73 61 6d   This is the sam
1d210 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
1d220 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74 68  e that was.** th
1d230 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1d240 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1d250 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1d260 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a  r its variants.*
1d270 2a 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  * that was used 
1d280 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 73 74  to create the st
1d290 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
1d2a0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73  irst place..*/.s
1d2b0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
1d2c0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
1d2d0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a  3_stmt*);.../*.*
1d2e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d  * CAPI3REF: Comm
1d2f0 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20  it And Rollback 
1d300 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
1d310 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 65  lbacks.**.** The
1d320 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72  se routines.** r
1d330 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1d340 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 62 65   functions to be
1d350 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
1d360 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  r a transaction.
1d370 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 20  ** is committed 
1d380 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 20  or rolled back. 
1d390 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   The pArg argume
1d3a0 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
1d3b0 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ough.** to the c
1d3c0 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68 65  allback.  If the
1d3d0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63   callback on a c
1d3e0 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74  ommit hook funct
1d3f0 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20  ion .** returns 
1d400 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
1d410 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
1d420 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
1d430 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66  llback..**.** If
1d440 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f   another functio
1d450 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79  n was previously
1d460 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73   registered, its
1d470 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72   pArg value is r
1d480 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65  eturned..** Othe
1d490 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65  rwise NULL is re
1d4a0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  turned..**.** Re
1d4b0 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
1d4c0 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
1d4d0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
1d4e0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
1d4f0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
1d500 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
1d510 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
1d520 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c  ve been .** roll
1d530 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
1d540 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
1d550 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
1d560 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
1d570 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
1d580 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
1d590 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
1d5a0 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54 68 65 20  k to occur. The 
1d5b0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
1d5c0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
1d5d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
1d5e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
1d5f0 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62 65 63  lled.** back bec
1d600 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
1d610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1d620 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
1d630 65 73 65 20 61 72 65 20 65 78 70 65 72 69 6d 65  ese are experime
1d640 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
1d650 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74 20  and are subject 
1d660 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f  to change..*/.vo
1d670 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  id *sqlite3_comm
1d680 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  it_hook(sqlite3*
1d690 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
1d6a0 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
1d6b0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
1d6c0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76  hook(sqlite3*, v
1d6d0 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20  oid(*)(void *), 
1d6e0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1d6f0 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68  API3REF: Data Ch
1d700 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f  ange Notificatio
1d710 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
1d720 2a 20 52 65 67 69 73 74 65 72 20 61 20 63 61 6c  * Register a cal
1d730 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1d740 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
1d750 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e   connection iden
1d760 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  tified by the .*
1d770 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  * first argument
1d780 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
1d790 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
1d7a0 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
1d7b0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
1d7c0 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
1d7d0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
1d7e0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
1d7f0 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73  nction for the s
1d800 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  ame .** database
1d810 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
1d820 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
1d830 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1d840 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
1d850 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
1d860 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
1d870 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70   a .** row is up
1d880 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
1d890 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 68 65 20  or deleted. The 
1d8a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1d8b0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1d8c0 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74  s.** a copy of t
1d8d0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1d8e0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  t to sqlite3_upd
1d8f0 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68 65 20  ate_hook(). The 
1d900 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
1d910 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
1d920 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f 49 4e  one of SQLITE_IN
1d930 53 45 52 54 2c 20 53 51 4c 49 54 45 5f 44 45 4c  SERT, SQLITE_DEL
1d940 45 54 45 20 6f 72 20 53 51 4c 49 54 45 5f 55 50  ETE or SQLITE_UP
1d950 44 41 54 45 2c 20 64 65 70 65 6e 64 69 6e 67 0a  DATE, depending.
1d960 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ** on the operat
1d970 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
1d980 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20  the callback to 
1d990 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68 65 20  be invoked. The 
1d9a0 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f  third and .** fo
1d9b0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
1d9c0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
1d9d0 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
1d9e0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
1d9f0 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61  and .** table na
1da00 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
1da10 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 20  e affected row. 
1da20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
1da30 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
1da40 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f 66  .** the rowid of
1da50 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 65   the row. In the
1da60 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61   case of an upda
1da70 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  te, this is the 
1da80 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20  rowid after .** 
1da90 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
1daa0 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   place..**.** Th
1dab0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73  e update hook is
1dac0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
1dad0 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
1dae0 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20  m tables are.** 
1daf0 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73  modified (i.e. s
1db00 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64  qlite_master and
1db10 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65   sqlite_sequence
1db20 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  )..**.** If anot
1db30 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73  her function was
1db40 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
1db50 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67  stered, its pArg
1db60 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
1db70 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65  ed..** Otherwise
1db80 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
1db90 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  d..*/.void *sqli
1dba0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
1dbb0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
1dbc0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
1dbd0 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
1dbe0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
1dbf0 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
1dc00 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
1dc10 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c  CAPI3REF:  Enabl
1dc20 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
1dc30 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
1dc40 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
1dc50 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
1dc60 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
1dc70 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
1dc80 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
1dc90 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
1dca0 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 63  ctures between c
1dcb0 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74 68  onnections to th
1dcc0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e  e same database.
1dcd0 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20 65  .** Sharing is e
1dce0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
1dcf0 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20 61  gument is true a
1dd00 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74  nd disabled if t
1dd10 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  he argument.** i
1dd20 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 42  s false..**.** B
1dd30 65 67 69 6e 6e 69 6e 67 20 69 6e 20 53 51 4c 69  eginning in SQLi
1dd40 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1dd50 2c 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20  , cache sharing 
1dd60 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
1dd70 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61  isabled.** for a
1dd80 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
1dd90 2e 20 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  .  In prior vers
1dda0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20  ions of SQLite, 
1ddb0 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65  sharing was.** e
1ddc0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
1ddd0 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
1dde0 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
1ddf0 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73  *.** The cache s
1de00 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
1de10 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
1de20 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
1de30 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
1de40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
1de50 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1de60 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
1de70 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1de80 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
1de90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1dea0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
1deb0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
1dec0 64 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 69  de that was.** i
1ded0 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
1dee0 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
1def0 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72  pened..**.** Vir
1df00 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e  tual tables cann
1df10 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ot be used with 
1df20 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20  a shared cache. 
1df30 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20   When shared.** 
1df40 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
1df50 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
1df60 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
1df70 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69  API used to regi
1df80 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20  ster.** virtual 
1df90 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61  tables will alwa
1dfa0 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
1dfb0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  or..**.** This r
1dfc0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
1dfd0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
1dfe0 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a  ared cache was.*
1dff0 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  * enabled or dis
1e000 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c  abled successful
1e010 6c 79 2e 20 20 41 6e 20 5b 53 51 4c 49 54 45 5f  ly.  An [SQLITE_
1e020 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f  ERROR | error co
1e030 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  de].** is return
1e040 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
1e050 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65  .** Shared cache
1e060 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1e070 64 65 66 61 75 6c 74 2e 20 20 42 75 74 20 74 68  default.  But th
1e080 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  is might change 
1e090 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c  in.** future rel
1e0a0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
1e0b0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
1e0c0 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73  hat care about s
1e0d0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73  hared.** cache s
1e0e0 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65  etting should se
1e0f0 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e  t it explicitly.
1e100 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e110 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
1e120 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
1e130 20 43 41 50 49 33 52 45 46 3a 20 20 41 74 74 65   CAPI3REF:  Atte
1e140 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
1e150 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 41 74   Memory.**.** At
1e160 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 4e 20  tempt to free N 
1e170 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65  bytes of heap me
1e180 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61  mory by dealloca
1e190 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  ting non-essenti
1e1a0 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  al.** memory all
1e1b0 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79  ocations held by
1e1c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69   the database li
1e1d0 62 72 61 72 79 20 28 65 78 61 6d 70 6c 65 3a 20  brary (example: 
1e1e0 6d 65 6d 6f 72 79 20 0a 2a 2a 20 75 73 65 64 20  memory .** used 
1e1f0 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
1e200 65 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f  e pages to impro
1e210 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 29 2e  ve performance).
1e220 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e230 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
1e240 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1e250 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20  3REF:  Impose A 
1e260 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
1e270 7a 65 0a 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20 61  ze.**.** Place a
1e280 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e   "soft" limit on
1e290 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
1e2a0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
1e2b0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
1e2c0 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 20  .** by SQLite.  
1e2d0 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
1e2e0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
1e2f0 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20  uested .** that 
1e300 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
1e310 20 73 70 65 63 69 66 69 65 64 20 6c 69 6d 69 74   specified limit
1e320 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  , [sqlite3_relea
1e330 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a  se_memory()] is.
1e340 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f  ** invoked one o
1e350 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
1e360 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61  free up some spa
1e370 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c  ce before the al
1e380 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d  location.** is m
1e390 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  ade..**.** The l
1e3a0 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
1e3b0 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69  soft", because i
1e3c0 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  f [sqlite3_relea
1e3d0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e  se_memory()] can
1e3e0 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66 66  not.** free suff
1e3f0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f  icient memory to
1e400 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d   prevent the lim
1e410 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78  it from being ex
1e420 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d  ceeded,.** the m
1e430 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
1e440 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68  ed anyway and th
1e450 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  e current operat
1e460 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a  ion proceeds..**
1e470 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f  .** A negative o
1e480 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
1e490 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
1e4a0 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
1e4b0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
1e4c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
1e4d0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
1e4e0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
1e4f0 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
1e500 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65  xhausted..** The
1e510 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
1e520 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
1e530 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
1e540 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
1e550 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
1e560 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
1e570 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20  ft heap limit.  
1e580 42 75 74 20 69 66 20 69 74 0a 2a 2a 20 69 73 20  But if it.** is 
1e590 75 6e 61 62 6c 65 20 74 6f 20 72 65 64 75 63 65  unable to reduce
1e5a0 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62 65   memory usage be
1e5b0 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 6c 69 6d  low the soft lim
1e5c0 69 74 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69  it, execution wi
1e5d0 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77  ll.** continue w
1e5e0 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20  ithout error or 
1e5f0 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54  notification.  T
1e600 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c  his is why the l
1e610 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c  imit is .** call
1e620 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  ed a "soft" limi
1e630 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f  t.  It is adviso
1e640 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  ry only..**.** T
1e650 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
1e660 69 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  it is implemente
1e670 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
1e680 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
1e690 6d 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  m()].** interfac
1e6a0 65 2e 20 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  e.  Only a singl
1e6b0 65 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20 69  e memory alarm i
1e6c0 73 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  s available in t
1e6d0 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 69 6d  he default.** im
1e6e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1e6f0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
1e700 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
1e710 6e 20 61 6c 73 6f 20 75 73 65 73 20 74 68 65 0a  n also uses the.
1e720 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20  ** memory alarm 
1e730 69 6e 74 65 72 66 61 63 65 20 69 74 20 77 69 6c  interface it wil
1e740 6c 20 69 6e 74 65 72 66 65 72 65 20 77 69 74 68  l interfere with
1e750 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
1e760 66 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65  f the.** soft he
1e770 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 75 6e 64  ap limit and und
1e780 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 20  efined behavior 
1e790 77 69 6c 6c 20 72 65 73 75 6c 74 2e 20 20 0a 2a  will result.  .*
1e7a0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1e7b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1e7c0 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .0, this routine
1e7d0 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65   only constraine
1e7e0 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  d the memory.** 
1e7f0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73  allocated by a s
1e800 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74  ingle thread - t
1e810 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
1e820 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75  n which this rou
1e830 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42  tine.** runs.  B
1e840 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51  eginning with SQ
1e850 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1e860 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61  .0, the soft hea
1e870 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70  p limit is.** ap
1e880 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72  plied to all thr
1e890 65 61 64 73 2e 20 20 54 68 65 20 76 61 6c 75 65  eads.  The value
1e8a0 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74   specified for t
1e8b0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
1e8c0 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65  it.** is an uppe
1e8d0 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74  r bound on the t
1e8e0 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  otal memory allo
1e8f0 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74  cation for all t
1e900 68 72 65 61 64 73 2e 20 20 49 6e 0a 2a 2a 20 76  hreads.  In.** v
1e910 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65  ersion 3.5.0 the
1e920 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69  re is no mechani
1e930 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20  sm for limiting 
1e940 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20 66  the heap usage f
1e950 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c  or.** individual
1e960 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69   threads..*/.voi
1e970 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  d sqlite3_soft_h
1e980 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a  eap_limit(int);.
1e990 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e9a0 20 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61    Extract Metada
1e9b0 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
1e9c0 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a  n Of A Table.**.
1e9d0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a  ** This routine.
1e9e0 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d  ** returns meta-
1e9f0 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65  data about a spe
1ea00 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20  cific column of 
1ea10 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62  a specific datab
1ea20 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63  ase.** table acc
1ea30 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68  essible using th
1ea40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  e connection han
1ea50 64 6c 65 20 70 61 73 73 65 64 20 61 73 20 74 68  dle passed as th
1ea60 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
1ea70 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   .** argument..*
1ea80 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20  *.** The column 
1ea90 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
1eaa0 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69   the second, thi
1eab0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
1eac0 72 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20  rameters to .** 
1ead0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54  this function. T
1eae0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1eaf0 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68  ter is either th
1eb00 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1eb10 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20  tabase.** (i.e. 
1eb20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f  "main", "temp" o
1eb30 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
1eb40 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
1eb50 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
1eb60 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
1eb70 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  L. If it is NULL
1eb80 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
1eb90 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
1eba0 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
1ebb0 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
1ebc0 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
1ebd0 69 74 68 6d 20 61 73 20 74 68 65 20 64 61 74 61  ithm as the data
1ebe0 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73  base engine uses
1ebf0 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20   to .** resolve 
1ec00 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
1ec10 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
1ec20 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e  .** The third an
1ec30 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
1ec40 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
1ec50 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
1ec60 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a  le and column .*
1ec70 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
1ec80 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
1ec90 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
1eca0 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
1ecb0 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20  ameters .** may 
1ecc0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d  be NULL..**.** M
1ecd0 65 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  eta information 
1ece0 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77  is returned by w
1ecf0 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65  riting to the me
1ed00 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70  mory locations p
1ed10 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20  assed as.** the 
1ed20 35 74 68 20 61 6e 64 20 73 75 62 73 65 71 75 65  5th and subseque
1ed30 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  nt parameters to
1ed40 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
1ed50 41 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a  Any of these .**
1ed60 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62   arguments may b
1ed70 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68  e NULL, in which
1ed80 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73   case the corres
1ed90 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20  ponding element 
1eda0 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f  of meta .** info
1edb0 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74  rmation is ommit
1edc0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ted..**.** <pre>
1edd0 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20  .** Parameter   
1ede0 20 20 4f 75 74 70 75 74 20 54 79 70 65 20 20 20    Output Type   
1edf0 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a     Description.*
1ee00 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  * --------------
1ee10 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ee20 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74  -----.**.**   5t
1ee30 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20  h         const 
1ee40 63 68 61 72 2a 20 20 20 20 20 20 44 61 74 61 20  char*      Data 
1ee50 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20  type.**   6th   
1ee60 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72        const char
1ee70 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74  *      Name of t
1ee80 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  he default colla
1ee90 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a  tion sequence .*
1eea0 2a 20 20 20 37 74 68 20 20 20 20 20 20 20 20 20  *   7th         
1eeb0 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20  int             
1eec0 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c   True if the col
1eed0 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55  umn has a NOT NU
1eee0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  LL constraint.**
1eef0 20 20 20 38 74 68 20 20 20 20 20 20 20 20 20 69     8th         i
1ef00 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
1ef10 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
1ef20 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  mn is part of th
1ef30 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a  e PRIMARY KEY.**
1ef40 20 20 20 39 74 68 20 20 20 20 20 20 20 20 20 69     9th         i
1ef50 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
1ef60 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
1ef70 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d  mn is AUTOINCREM
1ef80 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a  ENT.** </pre>.**
1ef90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
1efa0 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  y pointed to by 
1efb0 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f  the character po
1efc0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
1efd0 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c  for the .** decl
1efe0 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64  aration type and
1eff0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
1f000 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c  nce is valid onl
1f010 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  y until the next
1f020 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79   .** call to any
1f030 20 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63   sqlite API func
1f040 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tion..**.** If t
1f050 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62  he specified tab
1f060 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61  le is actually a
1f070 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65   view, then an e
1f080 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1f090 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
1f0a0 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
1f0b0 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
1f0c0 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
1f0d0 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45  nd an .** INTEGE
1f0e0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f  R PRIMARY KEY co
1f0f0 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78  lumn has been ex
1f100 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
1f110 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  d, then the outp
1f120 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ut .** parameter
1f130 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
1f140 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
1f150 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66  lared column. If
1f160 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20   there is no.** 
1f170 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
1f180 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20  red IPK column, 
1f190 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20  then the output 
1f1a0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
1f1b0 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  et as .** follow
1f1c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  s:.**.** <pre>.*
1f1d0 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a  *     data type:
1f1e0 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20   "INTEGER".**   
1f1f0 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75    collation sequ
1f200 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a  ence: "BINARY".*
1f210 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20  *     not null: 
1f220 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79  0.**     primary
1f230 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61   key: 1.**     a
1f240 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30  uto increment: 0
1f250 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
1f260 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   This function m
1f270 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
1f280 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
1f290 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
1f2a0 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
1f2b0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
1f2c0 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
1f2d0 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
1f2e0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
1f2f0 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
1f300 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72  nd, an SQLITE er
1f310 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
1f320 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f  rned and an erro
1f330 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66  r message.** lef
1f340 74 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  t in the databas
1f350 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20  e handle (to be 
1f360 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20  retrieved using 
1f370 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1f380 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  )..**.** This AP
1f390 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
1f3a0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
1f3b0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
1f3c0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
1f3d0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
1f3e0 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f  _METADATA prepro
1f3f0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
1f400 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
1f410 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75  lite3_table_colu
1f420 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73  mn_metadata(.  s
1f430 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1f440 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
1f450 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20  nnection handle 
1f460 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1f470 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
1f480 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d   /* Database nam
1f490 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63  e or NULL */.  c
1f4a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
1f4b0 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61  eName,     /* Ta
1f4c0 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f  ble name */.  co
1f4d0 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
1f4e0 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c  nName,    /* Col
1f4f0 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68  umn name */.  ch
1f500 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74  ar const **pzDat
1f510 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54  aType,    /* OUT
1f520 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61  PUT: Declared da
1f530 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61  ta type */.  cha
1f540 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c  r const **pzColl
1f550 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50  Seq,     /* OUTP
1f560 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65  UT: Collation se
1f570 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20  quence name */. 
1f580 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20   int *pNotNull, 
1f590 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1f5a0 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
1f5b0 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
1f5c0 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20  int exists */.  
1f5d0 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79  int *pPrimaryKey
1f5e0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  ,           /* O
1f5f0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
1f600 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b  olumn part of PK
1f610 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f   */.  int *pAuto
1f620 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20  inc             
1f630 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
1f640 65 20 69 66 20 63 6f 6c 75 6d 73 20 69 73 20 61  e if colums is a
1f650 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f  uto-increment */
1f660 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1f670 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74  REF: Load An Ext
1f680 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74  ension.**.** Att
1f690 65 6d 70 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20  empt to load an 
1f6a0 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
1f6b0 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
1f6c0 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a  ed in the file.*
1f6d0 2a 20 7a 46 69 6c 65 2e 20 20 54 68 65 20 65 6e  * zFile.  The en
1f6e0 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
1f6f0 6f 63 2e 20 20 7a 50 72 6f 63 20 6d 61 79 20 62  oc.  zProc may b
1f700 65 20 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  e 0 in which cas
1f710 65 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66  e the.** name of
1f720 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
1f730 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71   defaults to "sq
1f740 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f  lite3_extension_
1f750 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74  init"..**.** Ret
1f760 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1f770 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b  on success and [
1f780 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
1f790 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20   something goes 
1f7a0 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  wrong..**.** If 
1f7b0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
1f7c0 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20  and pzErrMsg is 
1f7d0 6e 6f 74 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c  not 0, then fill
1f7e0 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20   *pzErrMsg with 
1f7f0 0a 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67  .** error messag
1f800 65 20 74 65 78 74 2e 20 20 54 68 65 20 63 61 6c  e text.  The cal
1f810 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
1f820 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d  ould free this m
1f830 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c  emory.** by call
1f840 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1f850 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65  e()]..**.** Exte
1f860 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75  nsion loading mu
1f870 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73  st be enabled us
1f880 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
1f890 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
1f8a0 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74  on()].** prior t
1f8b0 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41  o calling this A
1f8c0 50 49 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77  PI or an error w
1f8d0 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
1f8e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f8f0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
1f900 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1f910 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
1f920 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
1f930 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
1f940 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
1f950 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
1f960 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
1f970 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
1f980 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
1f990 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
1f9a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
1f9b0 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
1f9c0 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
1f9d0 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
1f9e0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
1f9f0 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
1fa00 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
1fa10 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
1fa20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fa30 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  F:  Enable Or Di
1fa40 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20  sable Extension 
1fa50 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f  Loading.**.** So
1fa60 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
1fa70 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
1fa80 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
1fa90 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
1faa0 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
1fab0 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
1fac0 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
1fad0 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
1fae0 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
1faf0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
1fb00 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
1fb10 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
1fb20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  the following.**
1fb30 20 41 50 49 20 69 73 20 70 72 6f 76 69 64 65 64   API is provided
1fb40 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
1fb50 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
1fb60 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
1fb70 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e  m on and.** off.
1fb80 20 20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64    It is off by d
1fb90 65 66 61 75 6c 74 2e 20 20 53 65 65 20 74 69 63  efault.  See tic
1fba0 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a  ket #1863..**.**
1fbb0 20 43 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   Call this routi
1fbc0 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31  ne with onoff==1
1fbd0 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
1fbe0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a  on loading on.**
1fbf0 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74   and call it wit
1fc00 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75  h onoff==0 to tu
1fc10 72 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61  rn it back off a
1fc20 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gain..*/.int sql
1fc30 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
1fc40 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74  _extension(sqlit
1fc50 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66  e3 *db, int onof
1fc60 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
1fc70 52 45 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67  REF: Make Arrang
1fc80 65 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61  ements To Automa
1fc90 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20  tically Load An 
1fca0 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  Extension.**.** 
1fcb0 52 65 67 69 73 74 65 72 20 61 6e 20 65 78 74 65  Register an exte
1fcc0 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e  nsion entry poin
1fcd0 74 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61  t that is automa
1fce0 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a  tically invoked.
1fcf0 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ** whenever a ne
1fd00 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1fd10 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20  ction is opened 
1fd20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1fd30 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1fd40 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
1fd50 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
1fd60 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  v2()]..**.** Thi
1fd70 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76  s API can be inv
1fd80 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20  oked at program 
1fd90 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72  startup in order
1fda0 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
1fdb0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74  one or more stat
1fdc0 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78  ically linked ex
1fdd0 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69  tensions that wi
1fde0 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a  ll be available.
1fdf0 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61  ** to all new da
1fe00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1fe10 6e 73 2e 0a 2a 2a 0a 2a 2a 20 44 75 70 6c 69 63  ns..**.** Duplic
1fe20 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  ate extensions a
1fe30 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63  re detected so c
1fe40 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1fe50 69 6e 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ine multiple.** 
1fe60 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
1fe70 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73  ame extension is
1fe80 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a   harmless..**.**
1fe90 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   This routine st
1fea0 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ores a pointer t
1feb0 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  o the extension 
1fec0 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74  in an array.** t
1fed0 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20  hat is obtained 
1fee0 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2e 20 20  from malloc().  
1fef0 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d  If you run a mem
1ff00 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63  ory leak.** chec
1ff10 6b 65 72 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67  ker on your prog
1ff20 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72  ram and it repor
1ff30 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73  ts a leak becaus
1ff40 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 61 72 72  e of this.** arr
1ff50 61 79 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  ay, then invoke 
1ff60 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d 61 74  [sqlite3_automat
1ff70 69 63 5f 65 78 74 65 6e 73 69 6f 6e 5f 72 65 73  ic_extension_res
1ff80 65 74 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74  et()] prior.** t
1ff90 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72  o shutdown to fr
1ffa0 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a  ee the memory..*
1ffb0 2a 0a 2a 2a 20 41 75 74 6f 6d 61 74 69 63 20 65  *.** Automatic e
1ffc0 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
1ffd0 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
1ffe0 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ds..**.** This i
1fff0 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
20000 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
20010 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
20020 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20  e or.** removal 
20030 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
20040 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
20050 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74  .int sqlite3_aut
20060 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64  o_extension(void
20070 20 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a   *xEntryPoint);.
20080 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20090 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69  : Reset Automati
200a0 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  c Extension Load
200b0 69 6e 67 0a 2a 2a 0a 2a 2a 20 44 69 73 61 62 6c  ing.**.** Disabl
200c0 65 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79  e all previously
200d0 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f   registered auto
200e0 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
200f0 2e 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69  .  This.** routi
20100 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
20110 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
20120 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d  r [sqlite3_autom
20130 61 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e 28 29  atic_extension()
20140 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  ].** calls..**.*
20150 2a 20 54 68 69 73 20 63 61 6c 6c 20 64 69 73 61  * This call disa
20160 62 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65  bled automatic e
20170 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c  xtensions in all
20180 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20   threads..**.** 
20190 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  This interface i
201a0 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
201b0 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
201c0 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65   change or.** re
201d0 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
201e0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
201f0 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  te..*/.void sqli
20200 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
20210 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  xtension(void);.
20220 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45  ../*.****** EXPE
20230 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65  RIMENTAL - subje
20240 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74  ct to change wit
20250 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a  hout notice ****
20260 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a  **********.**.**
20270 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
20280 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
20290 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73  ble mechanism is
202a0 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
202b0 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
202c0 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
202d0 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
202e0 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
202f0 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
20300 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
20310 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
20320 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
20330 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
20340 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
20350 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
20360 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
20370 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  ablizes, we will
20380 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
20390 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
203a0 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
203b0 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
203c0 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
203d0 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72  t..*/../*.** Str
203e0 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20  uctures used by 
203f0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
20400 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74  e interface.*/.t
20410 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
20420 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74  lite3_vtab sqlit
20430 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66  e3_vtab;.typedef
20440 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
20450 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74  index_info sqlit
20460 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74  e3_index_info;.t
20470 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
20480 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
20490 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  r sqlite3_vtab_c
204a0 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73  ursor;.typedef s
204b0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
204c0 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64  dule sqlite3_mod
204d0 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 6d 6f  ule;../*.** A mo
204e0 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73 20  dule is a class 
204f0 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  of virtual table
20500 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  s.  Each module 
20510 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79  is defined.** by
20520 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
20530 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
20540 72 75 63 74 75 72 65 2e 20 20 54 68 69 73 20 73  ructure.  This s
20550 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74  tructure consist
20560 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  s.** mostly of m
20570 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
20580 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74  odule..*/.struct
20590 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
205a0 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
205b0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  ;.  int (*xCreat
205c0 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  e)(sqlite3*, voi
205d0 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
205e0 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
205f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
20600 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
20610 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
20620 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
20630 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
20640 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  *xConnect)(sqlit
20650 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
20660 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
20670 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
20680 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
20690 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
206a0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
206b0 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
206c0 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e  .  int (*xBestIn
206d0 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61  dex)(sqlite3_vta
206e0 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
206f0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a  3_index_info*);.
20700 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e    int (*xDisconn
20710 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ect)(sqlite3_vta
20720 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
20730 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c   (*xDestroy)(sql
20740 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
20750 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  );.  int (*xOpen
20760 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
20770 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76  pVTab, sqlite3_v
20780 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43  tab_cursor **ppC
20790 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ursor);.  int (*
207a0 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
207b0 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
207c0 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
207d0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
207e0 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
207f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
20800 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
20810 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
20820 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
20830 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78  argv);.  int (*x
20840 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74  Next)(sqlite3_vt
20850 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
20860 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74  nt (*xEof)(sqlit
20870 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
20880 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d  ;.  int (*xColum
20890 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  n)(sqlite3_vtab_
208a0 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
208b0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
208c0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  .  int (*xRowid)
208d0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
208e0 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  rsor*, sqlite3_i
208f0 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20  nt64 *pRowid);. 
20900 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28   int (*xUpdate)(
20910 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20  sqlite3_vtab *, 
20920 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  int, sqlite3_val
20930 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69  ue **, sqlite3_i
20940 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28  nt64 *);.  int (
20950 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33  *xBegin)(sqlite3
20960 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
20970 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
20980 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
20990 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d  b);.  int (*xCom
209a0 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
209b0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
209c0 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71   (*xRollback)(sq
209d0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
209e0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  b);.  int (*xFin
209f0 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74  dFunction)(sqlit
20a00 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
20a10 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20  int nArg, const 
20a20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20  char *zName,.   
20a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20a40 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75      void (**pxFu
20a50 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
20a60 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
20a70 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20  _value**),.     
20a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20a90 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b    void **ppArg);
20aa0 0a 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d  ..  int (*xRenam
20ab0 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
20ac0 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68  *pVtab, const ch
20ad0 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f  ar *zNew);.};../
20ae0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
20af0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
20b00 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
20b10 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
20b20 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69  sed to.** pass i
20b30 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20  nformation into 
20b40 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20  and receive the 
20b50 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78  reply from the x
20b60 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74  BestIndex.** met
20b70 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  hod of an sqlite
20b80 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66  3_module.  The f
20b90 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e  ields under **In
20ba0 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a  puts** are the.*
20bb0 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73  * inputs to xBes
20bc0 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72  tIndex and are r
20bd0 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74  ead-only.  xBest
20be0 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74  Index inserts it
20bf0 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  s.** results int
20c00 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a  o the **Outputs*
20c10 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20  * fields..**.** 
20c20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
20c30 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20  ] array records 
20c40 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
20c50 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 0a  straints of the.
20c60 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20  ** form:.**.**  
20c70 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50         column OP
20c80 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72   expr.**.** Wher
20c90 65 20 4f 50 20 69 73 20 3d 2c 20 3c 2c 20 3c 3d  e OP is =, <, <=
20ca0 2c 20 3e 2c 20 6f 72 20 3e 3d 2e 20 20 54 68 65  , >, or >=.  The
20cb0 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
20cc0 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a 2a  ator is stored.*
20cd0 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  * in aConstraint
20ce0 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65  [].op.  The inde
20cf0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
20d00 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a  is stored in .**
20d10 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
20d20 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72  Column.  aConstr
20d30 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
20d40 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
20d50 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
20d60 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
20d70 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
20d80 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
20d90 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
20da0 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
20db0 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a   it cannot..**.*
20dc0 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20  * The optimizer 
20dd0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
20de0 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74  verts terms of t
20df0 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50  he form "expr OP
20e00 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20   column".** and 
20e10 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70  makes other simp
20e20 6c 69 66 69 63 61 74 69 6e 6f 73 20 74 6f 20 74  lificatinos to t
20e30 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
20e40 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
20e50 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20  .** get as many 
20e60 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
20e70 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d  ms into the form
20e80 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20   shown above as 
20e90 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  possible..** The
20ea0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
20eb0 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74  rray only report
20ec0 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  s WHERE clause t
20ed0 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72  erms in the corr
20ee0 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74  ect.** form that
20ef0 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61   refer to the pa
20f00 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c  rticular virtual
20f10 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65   table being que
20f20 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f  ried..**.** Info
20f30 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
20f40 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
20f50 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  e is stored in a
20f60 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61  OrderBy[]..** Ea
20f70 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65  ch term of aOrde
20f80 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f  rBy records a co
20f90 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45  lumn of the ORDE
20fa0 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a  R BY clause..**.
20fb0 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 65  ** The xBestInde
20fc0 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69  x method must fi
20fd0 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  ll aConstraintUs
20fe0 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72  age[] with infor
20ff0 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
21000 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20  what parameters 
21010 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74  to pass to xFilt
21020 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65  er.  If argvInde
21030 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  x>0 then.** the 
21040 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
21050 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
21060 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74  ding aConstraint
21070 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a  [] is evaluated.
21080 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74  ** and becomes t
21090 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20  he argvIndex-th 
210a0 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20  entry in argv.  
210b0 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
210c0 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
210d0 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
210e0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
210f0 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
21100 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
21110 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
21120 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
21130 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
21140 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
21150 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74  idxNum and idxPt
21160 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63  r values are rec
21170 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64  orded and passed
21180 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a   into xFilter..*
21190 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  * sqlite3_free()
211a0 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65   is used to free
211b0 20 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 54   idxPtr if needT
211c0 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74  oFreeIdxPtr is t
211d0 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  rue..**.** The o
211e0 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d  rderByConsumed m
211f0 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74  eans that output
21200 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69   from xFilter wi
21210 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
21220 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
21230 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
21240 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
21250 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
21260 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
21270 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
21280 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d  .**.** The estim
21290 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69  atedCost value i
212a0 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  s an estimate of
212b0 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69   the cost of doi
212c0 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63  ng the.** partic
212d0 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20  ular lookup.  A 
212e0 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74  full scan of a t
212f0 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72  able with N entr
21300 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a  ies should have.
21310 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20  ** a cost of N. 
21320 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68   A binary search
21330 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e   of a table of N
21340 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
21350 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f  have a.** cost o
21360 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  f approximately 
21370 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63  log(N)..*/.struc
21380 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
21390 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75  info {.  /* Inpu
213a0 74 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e  ts */.  const in
213b0 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20  t nConstraint;  
213c0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
213d0 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73  entries in aCons
213e0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 63 6f 6e 73  traint */.  cons
213f0 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
21400 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e  _index_constrain
21410 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  t {.     int iCo
21420 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
21430 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20     /* Column on 
21440 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
21450 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  f constraint */.
21460 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
21470 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f  ar op;         /
21480 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65  * Constraint ope
21490 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e  rator */.     un
214a0 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62  signed char usab
214b0 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20  le;     /* True 
214c0 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  if this constrai
214d0 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a  nt is usable */.
214e0 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66       int iTermOf
214f0 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f  fset;          /
21500 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  * Used internall
21510 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73  y - xBestIndex s
21520 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a  hould ignore */.
21530 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e 73    } *const aCons
21540 74 72 61 69 6e 74 3b 20 20 20 20 20 20 2f 2a 20  traint;      /* 
21550 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63  Table of WHERE c
21560 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
21570 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74  s */.  const int
21580 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20   nOrderBy;      
21590 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74    /* Number of t
215a0 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45  erms in the ORDE
215b0 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20  R BY clause */. 
215c0 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
215d0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65  lite3_index_orde
215e0 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  rby {.     int i
215f0 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
21600 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e       /* Column n
21610 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e  umber */.     un
21620 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63  signed char desc
21630 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20  ;       /* True 
21640 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65  for DESC.  False
21650 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d   for ASC. */.  }
21660 20 2a 63 6f 6e 73 74 20 61 4f 72 64 65 72 42 79   *const aOrderBy
21670 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65  ;         /* The
21680 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
21690 20 2a 2f 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74   */..  /* Output
216a0 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  s */.  struct sq
216b0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73  lite3_index_cons
216c0 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20  traint_usage {. 
216d0 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78     int argvIndex
216e0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69  ;           /* i
216f0 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74  f >0, constraint
21700 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76   is part of argv
21710 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20   to xFilter */. 
21720 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
21730 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44   omit;      /* D
21740 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73  o not code a tes
21750 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74  t for this const
21760 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 63 6f  raint */.  } *co
21770 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  nst aConstraintU
21780 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e  sage;.  int idxN
21790 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  um;             
217a0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65     /* Number use
217b0 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68  d to identify th
217c0 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61  e index */.  cha
217d0 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
217e0 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
217f0 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
21800 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
21810 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e  3_malloc */.  in
21820 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53  t needToFreeIdxS
21830 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65  tr;      /* Free
21840 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71   idxStr using sq
21850 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20  lite3_free() if 
21860 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72  true */.  int or
21870 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20  derByConsumed;  
21880 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
21890 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64  output is alread
218a0 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64  y ordered */.  d
218b0 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43  ouble estimatedC
218c0 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74  ost;      /* Est
218d0 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75  imated cost of u
218e0 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20  sing this index 
218f0 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51  */.};.#define SQ
21900 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
21910 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64  RAINT_EQ    2.#d
21920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
21930 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54  EX_CONSTRAINT_GT
21940 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
21950 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
21960 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64  RAINT_LE    8.#d
21970 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
21980 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54  EX_CONSTRAINT_LT
21990 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
219a0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
219b0 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a  TRAINT_GE    32.
219c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
219d0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
219e0 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20  MATCH 64../*.** 
219f0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
21a00 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
21a10 20 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61   a new module na
21a20 6d 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74  me with an SQLit
21a30 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
21a40 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d    Module names m
21a50 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
21a60 64 20 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e  d before creatin
21a70 67 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c  g new.** virtual
21a80 20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d   tables on the m
21a90 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65  odule, or before
21aa0 20 75 73 69 6e 67 20 70 72 65 65 78 69 73 74 69   using preexisti
21ab0 6e 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  ng virtual.** ta
21ac0 62 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  bles of the modu
21ad0 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  le..*/.int sqlit
21ae0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
21af0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
21b00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
21b10 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
21b20 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
21b30 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
21b40 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
21b50 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
21b60 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
21b70 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
21b80 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20  ite3_module *,  
21b90 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
21ba0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
21bb0 20 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20   void *         
21bc0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
21bd0 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
21be0 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
21bf0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69  */.);../*.** Thi
21c00 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65  s routine is ide
21c10 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71  ntical to the sq
21c20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
21c30 75 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f  ule() method abo
21c40 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ve,.** except th
21c50 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64  at it allows a d
21c60 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
21c70 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69  on to be specifi
21c80 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65  ed. It is.** eve
21c90 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e  n more experimen
21ca0 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73  tal than the res
21cb0 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  t of the virtual
21cc0 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a   tables API..*/.
21cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
21ce0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20  te_module_v2(.  
21cf0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
21d00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
21d10 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
21d20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
21d30 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
21d40 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
21d50 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
21d60 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
21d70 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
21d80 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a  _module *,    /*
21d90 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
21da0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
21db0 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
21dc0 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
21dd0 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
21de0 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20  te/xConnect */. 
21df0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
21e00 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d  (void*)     /* M
21e10 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72  odule destructor
21e20 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a   function */.);.
21e30 0a 2f 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64  ./*.** Every mod
21e40 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
21e50 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
21e60 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ss of the follow
21e70 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ing structure.**
21e80 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70   to describe a p
21e90 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
21ea0 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ce of the module
21eb0 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73  .  Each subclass
21ec0 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 79 6c   will.** be tayl
21ed0 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63  ored to the spec
21ee0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68  ific needs of th
21ef0 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  e module impleme
21f00 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a  ntation.   The.*
21f10 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69  * purpose of thi
21f20 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20  s superclass is 
21f30 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69  to define certai
21f40 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72  n fields that ar
21f50 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61  e common.** to a
21f60 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ll module implem
21f70 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  entations..**.**
21f80 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
21f90 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20  methods can set 
21fa0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
21fb0 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a   by assigning a.
21fc0 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  ** string obtain
21fd0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
21fe0 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72  mprintf() to zEr
21ff0 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f  rMsg.  The metho
22000 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65  d should.** take
22010 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70   care that any p
22020 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66  rior string is f
22030 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  reed by a call t
22040 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
22050 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73  .** prior to ass
22060 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72  igning a new str
22070 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ing to zErrMsg. 
22080 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   After the error
22090 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
220a0 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
220b0 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
220c0 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
220d0 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
220e0 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
220f0 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
22100 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
22110 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
22120 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a   zeroed.  Note.*
22130 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d  * that sqlite3_m
22140 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
22150 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20  ite3_free() are 
22160 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72  used on the zErr
22170 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e  Msg field.** sin
22180 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ce virtual table
22190 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69  s are commonly i
221a0 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f  mplemented in lo
221b0 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
221c0 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f  s which.** do no
221d0 74 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f  t have access to
221e0 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28   sqlite3MPrintf(
221f0 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65  ) or sqlite3Free
22200 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ()..*/.struct sq
22210 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
22220 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
22230 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
22240 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
22250 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
22260 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
22270 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
22280 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
22290 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20   internally */. 
222a0 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
222b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
222c0 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
222d0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
222e0 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
222f0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
22300 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
22310 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
22320 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
22330 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76  lds */.};../* Ev
22340 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ery module imple
22350 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
22360 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
22370 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
22380 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72  ture.** to descr
22390 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74  ibe cursors that
223a0 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20   point into the 
223b0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e  virtual table an
223c0 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
223d0 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
223e0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
223f0 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
22400 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
22410 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  ** xOpen method 
22420 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
22430 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  Each module impl
22440 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
22450 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f  define.** the co
22460 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f  ntent of a curso
22470 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73  r structure to s
22480 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64  uit its own need
22490 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75  s..**.** This su
224a0 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20  perclass exists 
224b0 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69  in order to defi
224c0 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65  ne fields of the
224d0 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20   cursor that.** 
224e0 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  are common to al
224f0 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  l implementation
22500 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  s..*/.struct sql
22510 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
22520 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61   {.  sqlite3_vta
22530 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f  b *pVtab;      /
22540 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
22550 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a  of this cursor *
22560 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
22570 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
22580 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
22590 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
225a0 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
225b0 0a 2f 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61  ./*.** The xCrea
225c0 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20  te and xConnect 
225d0 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64  methods of a mod
225e0 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c  ule use the foll
225f0 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20  owing API.** to 
22600 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d  declare the form
22610 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e  at (the names an
22620 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74  d datatypes of t
22630 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a  he columns) of.*
22640 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  * the virtual ta
22650 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d  bles they implem
22660 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
22670 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
22680 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
22690 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61   char *zCreateTa
226a0 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72  ble);../*.** Vir
226b0 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20  tual tables can 
226c0 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74  provide alternat
226d0 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
226e0 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ons of functions
226f0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46  .** using the xF
22700 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68  indFunction meth
22710 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20  od.  But global 
22720 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73  versions of thos
22730 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d  e functions.** m
22740 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64  ust exist in ord
22750 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61  er to be overloa
22760 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ded..**.** This 
22770 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61  API makes sure a
22780 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20   global version 
22790 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  of a function wi
227a0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
227b0 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62  ** name and numb
227c0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
227d0 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20   exists.  If no 
227e0 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78  such function ex
227f0 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ists.** before t
22800 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65  his API is calle
22810 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f  d, a new functio
22820 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  n is created.  T
22830 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
22840 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20  n.** of the new 
22850 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20  function always 
22860 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74  causes an except
22870 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e  ion to be thrown
22880 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77  .  So.** the new
22890 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
228a0 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69   good for anythi
228b0 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49  ng by itself.  I
228c0 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f  ts only.** purpo
228d0 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c  se is to be a pl
228e0 61 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74  ace-holder funct
228f0 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20  ion that can be 
22900 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79  overloaded.** by
22910 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e   virtual tables.
22920 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
22930 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64  should be consid
22940 65 72 65 64 20 70 61 72 74 20 6f 66 20 74 68 65  ered part of the
22950 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
22960 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69  nterface,.** whi
22970 63 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ch is experiment
22980 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74  al and subject t
22990 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  o change..*/.int
229a0 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61   sqlite3_overloa
229b0 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74  d_function(sqlit
229c0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
229d0 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20  *zFuncName, int 
229e0 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  nArg);../*.** Th
229f0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
22a00 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
22a10 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e   mechanism defin
22a20 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75  ed above (back u
22a30 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e  p.** to a commen
22a40 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d  t remarkably sim
22a50 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65  ilar to this one
22a60 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  ) is currently c
22a70 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
22a80 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
22a90 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
22aa0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
22ab0 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
22ac0 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
22ad0 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
22ae0 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
22af0 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
22b00 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
22b10 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
22b20 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
22b30 6d 20 73 74 61 62 6c 69 7a 65 73 2c 20 77 65 20  m stablizes, we 
22b40 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
22b50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
22b60 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
22b70 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
22b80 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
22b90 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a  mment..**.******
22ba0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20   EXPERIMENTAL - 
22bb0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
22bc0 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
22bd0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a   **************.
22be0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
22bf0 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20  EF: A Handle To 
22c00 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a  An Open BLOB.**.
22c10 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
22c20 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
22c30 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
22c40 20 69 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a 20   is used to .** 
22c50 72 65 70 72 65 73 65 6e 74 20 61 6e 20 62 6c 6f  represent an blo
22c60 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62 6c 6f  b-handle.  A blo
22c70 62 2d 68 61 6e 64 6c 65 20 69 73 20 63 72 65 61  b-handle is crea
22c80 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ted by.** [sqlit
22c90 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
22ca0 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79  and destroyed by
22cb0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
22cc0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lose()]..** The 
22cd0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
22ce0 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
22cf0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
22d00 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63   interfaces.** c
22d10 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
22d20 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c  ad or write smal
22d30 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66  l subsections of
22d40 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68   the blob..** Th
22d50 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
22d60 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
22d70 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  ce returns the s
22d80 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c  ize of the.** bl
22d90 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a  ob in bytes..*/.
22da0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
22db0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69  qlite3_blob sqli
22dc0 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a  te3_blob;../*.**
22dd0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20   CAPI3REF: Open 
22de0 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65  A BLOB For Incre
22df0 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a  mental I/O.**.**
22e00 20 4f 70 65 6e 20 61 20 68 61 6e 64 6c 65 20 74   Open a handle t
22e10 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f 63 61 74  o the blob locat
22e20 65 64 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c  ed in row iRow,,
22e30 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c   column zColumn,
22e40 20 0a 2a 2a 20 74 61 62 6c 65 20 7a 54 61 62 6c   .** table zTabl
22e50 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44  e in database zD
22e60 62 2e 20 69 2e 65 2e 20 74 68 65 20 73 61 6d 65  b. i.e. the same
22e70 20 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c 64   blob that would
22e80 0a 2a 2a 20 62 65 20 73 65 6c 65 63 74 65 64 20  .** be selected 
22e90 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  by:.**.** <pre>.
22ea0 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43  **     SELECT zC
22eb0 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a  olumn FROM zDb.z
22ec0 54 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77 69  Table WHERE rowi
22ed0 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70  d = iRow;.** </p
22ee0 72 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  re>.**.** If the
22ef0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
22f00 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   is non-zero, th
22f10 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64  e blob is opened
22f20 20 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61 6e   for .** read an
22f30 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20  d write access. 
22f40 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74  If it is zero, t
22f50 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65  he blob is opene
22f60 64 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20 61  d for read .** a
22f70 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20  ccess..**.** On 
22f80 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45  success, [SQLITE
22f90 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
22fa0 20 61 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a   and the new .**
22fb0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
22fc0 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73   blob handle] is
22fd0 20 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42   written to *ppB
22fe0 6c 6f 62 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  lob..** Otherwis
22ff0 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  e an error code 
23000 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
23010 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 77 72  .** any value wr
23020 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62  itten to *ppBlob
23030 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
23040 73 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65  sed by the calle
23050 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  r..** This funct
23060 69 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61 74  ion sets the dat
23070 61 62 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 72  abase-handle err
23080 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
23090 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c  age.** accessibl
230a0 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65  e via [sqlite3_e
230b0 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73  rrcode()] and [s
230c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
230d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
230e0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71  _blob_open(.  sq
230f0 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20  lite3*,.  const 
23100 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e  char *zDb,.  con
23110 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c  st char *zTable,
23120 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
23130 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65  Column,.  sqlite
23140 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20  3_int64 iRow,.  
23150 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c  int flags,.  sql
23160 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c  ite3_blob **ppBl
23170 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ob.);../*.** CAP
23180 49 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 20  I3REF:  Close A 
23190 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  BLOB Handle.**.*
231a0 2a 20 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20  * Close an open 
231b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
231c0 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2f  blob handle]..*/
231d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
231e0 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f  b_close(sqlite3_
231f0 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  blob *);../*.** 
23200 43 41 50 49 33 52 45 46 3a 20 20 52 65 74 75 72  CAPI3REF:  Retur
23210 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e  n The Size Of An
23220 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a   Open BLOB.**.**
23230 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
23240 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65   in bytes of the
23250 20 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c 65   blob accessible
23260 20 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a 2a   via the open .*
23270 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
23280 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70  | blob-handle] p
23290 61 73 73 65 64 20 61 73 20 61 6e 20 61 72 67 75  assed as an argu
232a0 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ment..*/.int sql
232b0 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
232c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b  sqlite3_blob *);
232d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
232e0 3a 20 20 52 65 61 64 20 44 61 74 61 20 46 72 6f  :  Read Data Fro
232f0 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  m A BLOB Increme
23300 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69  ntally.**.** Thi
23310 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
23320 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20  ed to read data 
23330 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a  from an open .**
23340 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
23350 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e   blob-handle] in
23360 74 6f 20 61 20 63 61 6c 6c 65 72 20 73 75 70 70  to a caller supp
23370 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20  lied buffer..** 
23380 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  n bytes of data 
23390 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
233a0 62 75 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f 6d  buffer.** z from
233b0 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20   the open blob, 
233c0 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
233d0 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a  et iOffset..**.*
233e0 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51  * On success, SQ
233f0 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72  LITE_OK is retur
23400 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20  ned. Otherwise, 
23410 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  an .** [SQLITE_E
23420 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65 72  RROR | SQLite er
23430 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ror code] or an.
23440 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
23450 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
23460 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
23470 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  returned..*/.int
23480 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
23490 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ad(sqlite3_blob 
234a0 2a 2c 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20  *, void *z, int 
234b0 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  n, int iOffset);
234c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
234d0 3a 20 20 57 72 69 74 65 20 44 61 74 61 20 49 6e  :  Write Data In
234e0 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  to A BLOB Increm
234f0 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68  entally.**.** Th
23500 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
23510 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74  sed to write dat
23520 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a  a into an open .
23530 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
23540 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20   | blob-handle] 
23550 66 72 6f 6d 20 61 20 75 73 65 72 20 73 75 70 70  from a user supp
23560 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20  lied buffer..** 
23570 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  n bytes of data 
23580 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  are copied from 
23590 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f  the buffer.** po
235a0 69 6e 74 65 64 20 74 6f 20 62 79 20 7a 20 69 6e  inted to by z in
235b0 74 6f 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62  to the open blob
235c0 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
235d0 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
235e0 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
235f0 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d  te3_blob | blob-
23600 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61  handle] passed a
23610 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
23620 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  ment.** was not 
23630 6f 70 65 6e 65 64 20 66 6f 72 20 77 72 69 74 69  opened for writi
23640 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61  ng (the flags pa
23650 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
23660 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
23670 0a 2a 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20  .*** was zero), 
23680 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
23690 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45  turns [SQLITE_RE
236a0 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54  ADONLY]..**.** T
236b0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
236c0 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65   only modify the
236d0 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65   contents of the
236e0 20 62 6c 6f 62 2c 20 69 74 20 69 73 0a 2a 2a 20   blob, it is.** 
236f0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
23700 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a  increase the siz
23710 65 20 6f 66 20 61 20 62 6c 6f 62 20 75 73 69 6e  e of a blob usin
23720 67 20 74 68 69 73 20 41 50 49 2e 20 49 66 0a 2a  g this API. If.*
23730 2a 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  * offset iOffset
23740 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6e 20   is less than n 
23750 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65  bytes from the e
23760 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20  nd of the blob, 
23770 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
23780 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
23790 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72  nd no data is wr
237a0 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20  itten..**.** On 
237b0 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f  success, SQLITE_
237c0 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  OK is returned. 
237d0 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a  Otherwise, an .*
237e0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  * [SQLITE_ERROR 
237f0 7c 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63  | SQLite error c
23800 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53  ode] or an.** [S
23810 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
23820 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f   | extended erro
23830 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
23840 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
23850 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73  te3_blob_write(s
23860 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63  qlite3_blob *, c
23870 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e  onst void *z, in
23880 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74  t n, int iOffset
23890 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
238a0 45 46 3a 20 20 56 69 72 74 75 61 6c 20 46 69 6c  EF:  Virtual Fil
238b0 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73  e System Objects
238c0 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c  .**.** A virtual
238d0 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53   filesystem (VFS
238e0 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  ) is an [sqlite3
238f0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  _vfs] object.** 
23900 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73  that SQLite uses
23910 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20   to interact.** 
23920 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79  with the underly
23930 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
23940 73 74 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69 6c  stem.  Most buil
23950 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a  ds come with a.*
23960 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74  * single default
23970 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70   VFS that is app
23980 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65  ropriate for the
23990 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a   host computer..
239a0 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e  ** New VFSes can
239b0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61   be registered a
239c0 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65  nd existing VFSe
239d0 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73  s can be unregis
239e0 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f  tered..** The fo
239f0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
23a00 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e  es are provided.
23a10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23a20 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e  e3_vfs_find() in
23a30 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
23a40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56  a pointer to a V
23a50 46 53 20 67 69 76 65 6e 20 69 74 73 0a 2a 2a 20  FS given its.** 
23a60 6e 61 6d 65 2e 20 20 4e 61 6d 65 73 20 61 72 65  name.  Names are
23a70 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e   case sensitive.
23a80 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
23a90 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a 2a   match, a NULL.*
23aa0 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  * pointer is ret
23ab0 75 72 6e 65 64 2e 20 20 49 66 20 7a 56 66 73 4e  urned.  If zVfsN
23ac0 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ame is NULL then
23ad0 20 74 68 65 20 64 65 66 61 75 6c 74 20 0a 2a 2a   the default .**
23ae0 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65 64   VFS is returned
23af0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65  ..**.** New VFSe
23b00 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
23b10 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66   with sqlite3_vf
23b20 73 5f 72 65 67 69 73 74 65 72 28 29 2e 20 20 45  s_register().  E
23b30 61 63 68 0a 2a 2a 20 6e 65 77 20 56 46 53 20 62  ach.** new VFS b
23b40 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75  ecomes the defau
23b50 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d 61  lt VFS if the ma
23b60 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73  keDflt flag is s
23b70 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20  et..** The same 
23b80 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73  VFS can be regis
23b90 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
23ba0 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a  imes without inj
23bb0 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20  ury..** To make 
23bc0 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20  an existing VFS 
23bd0 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74  into the default
23be0 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69   VFS, register i
23bf0 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20  t again.** with 
23c00 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
23c10 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64  g set.  If two d
23c20 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77  ifferent VFSes w
23c30 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20  ith the.** same 
23c40 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65  name are registe
23c50 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f  red, the behavio
23c60 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  r is undefined. 
23c70 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20   If a.** VFS is 
23c80 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
23c90 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e  a name that is N
23ca0 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
23cb0 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20  string,.** then 
23cc0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
23cd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a 2a  undefined..** .*
23ce0 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56  * Unregister a V
23cf0 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69  FS with the sqli
23d00 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
23d10 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
23d20 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 6c  ** If the defaul
23d30 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73  t VFS is unregis
23d40 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56  tered, another V
23d50 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a  FS is chosen as.
23d60 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20  ** the default. 
23d70 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20   The choice for 
23d80 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61  the new VFS is a
23d90 72 62 69 74 72 61 72 79 2e 0a 2a 2f 0a 73 71 6c  rbitrary..*/.sql
23da0 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65  ite3_vfs *sqlite
23db0 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74  3_vfs_find(const
23dc0 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29   char *zVfsName)
23dd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66  ;.int sqlite3_vf
23de0 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74  s_register(sqlit
23df0 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b  e3_vfs*, int mak
23e00 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69  eDflt);.int sqli
23e10 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
23e20 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29  er(sqlite3_vfs*)
23e30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23e40 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a  F: Mutexes.**.**
23e50 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
23e60 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74   uses these rout
23e70 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a  ines for thread.
23e80 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69  ** synchronizati
23e90 6f 6e 2e 20 20 54 68 6f 75 67 68 20 74 68 65 79  on.  Though they
23ea0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
23eb0 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73  r internal.** us
23ec0 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64  e by SQLite, cod
23ed0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
23ee0 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a  inst SQLite is.*
23ef0 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75  * permitted to u
23f00 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  se any of these 
23f10 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
23f20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63  The SQLite sourc
23f30 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20  e code contains 
23f40 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
23f50 6e 74 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66 20  ntations .** of 
23f60 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74  these mutex rout
23f70 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70  ines.  An approp
23f80 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61  riate implementa
23f90 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63  tion.** is selec
23fa0 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ted automaticall
23fb0 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  y at compile-tim
23fc0 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  e.  The followin
23fd0 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  g.** implementat
23fe0 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62  ions are availab
23ff0 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  le in the SQLite
24000 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   core:.**.** <ul
24010 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49  >.** <li>   SQLI
24020 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20  TE_MUTEX_OS2.** 
24030 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
24040 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c  TEX_PTHREAD.** <
24050 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
24060 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20  EX_W32.** <li>  
24070 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f   SQLITE_MUTEX_NO
24080 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  OP.** </ul>.**.*
24090 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54  * The SQLITE_MUT
240a0 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e  EX_NOOP implemen
240b0 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20  tation is a set 
240c0 6f 66 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20  of routines .** 
240d0 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61  that does no rea
240e0 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73  l locking and is
240f0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
24100 20 75 73 65 20 69 6e 20 0a 2a 2a 20 61 20 73 69   use in .** a si
24110 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70  ngle-threaded ap
24120 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
24130 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32  SQLITE_MUTEX_OS2
24140 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  ,.** SQLITE_MUTE
24150 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53  X_PTHREAD, and S
24160 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20  QLITE_MUTEX_W32 
24170 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
24180 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61  ** are appropria
24190 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 6f 73  te for use on os
241a0 2f 32 2c 20 75 6e 69 78 2c 20 61 6e 64 20 77 69  /2, unix, and wi
241b0 6e 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  ndows..** .** If
241c0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
241d0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
241e0 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46  ITE_MUTEX_APPDEF
241f0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a   preprocessor.**
24200 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28   macro defined (
24210 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d  with "-DSQLITE_M
24220 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c  UTEX_APPDEF=1"),
24230 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a   then no mutex.*
24240 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
24250 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74   is included wit
24260 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 20  h the library.  
24270 54 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e 74  The.** mutex int
24280 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
24290 64 65 66 69 6e 65 64 20 68 65 72 65 20 62 65 63  defined here bec
242a0 6f 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a 20  ome external.** 
242b0 72 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74 68  references in th
242c0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
242d0 20 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c 65   for which imple
242e0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d 75  mentations.** mu
242f0 73 74 20 62 65 20 70 72 6f 76 69 64 65 64 20 62  st be provided b
24300 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
24310 6e 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69 74  n.  This facilit
24320 79 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20 61  y allows an.** a
24330 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
24340 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51  links against SQ
24350 4c 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65 20  Lite to provide 
24360 69 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a 2a  its own mutex.**
24370 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
24380 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
24390 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  o modify the SQL
243a0 69 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20  ite core..**.** 
243b0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
243c0 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  x_alloc() routin
243d0 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65  e allocates a ne
243e0 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72  w.** mutex and r
243f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
24400 20 74 6f 20 69 74 2e 20 20 49 66 20 69 74 20 72   to it.  If it r
24410 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74  eturns NULL.** t
24420 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61  hat means that a
24430 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74   mutex could not
24440 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20   be allocated.  
24450 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75  SQLite.** will u
24460 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20  nwind its stack 
24470 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72  and return an er
24480 72 6f 72 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ror.  The argume
24490 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
244a0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69  _mutex_alloc() i
244b0 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
244c0 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
244d0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
244e0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
244f0 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20  EX_FAST.** <li> 
24500 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
24510 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CURSIVE.** <li> 
24520 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
24530 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c  ATIC_MASTER.** <
24540 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
24550 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20  X_STATIC_MEM.** 
24560 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
24570 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a  EX_STATIC_MEM2.*
24580 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
24590 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
245a0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
245b0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
245c0 55 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  U.** </ul>.**.**
245d0 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63   The first two c
245e0 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73  onstants cause s
245f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
24600 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a  oc() to create.*
24610 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20  * a new mutex.  
24620 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73  The new mutex is
24630 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20   recursive when 
24640 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
24650 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65  URSIVE.** is use
24660 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73  d but not necess
24670 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51  arily so when SQ
24680 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
24690 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20  is used..** The 
246a0 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
246b0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
246c0 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73  ed to make a dis
246d0 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
246e0 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  een SQLITE_MUTEX
246f0 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53  _RECURSIVE and S
24700 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
24710 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   if it does.** n
24720 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 42 75 74  ot want to.  But
24730 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
24740 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75  y request a recu
24750 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a  rsive mutex in.*
24760 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74  * cases where it
24770 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e   really needs on
24780 65 2e 20 20 49 66 20 61 20 66 61 73 74 65 72 20  e.  If a faster 
24790 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75  non-recursive mu
247a0 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
247b0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
247c0 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70  le on the host p
247d0 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74  latform, the mut
247e0 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20  ex subsystem.** 
247f0 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 63  might return suc
24800 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73  h a mutex in res
24810 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f  ponse to SQLITE_
24820 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a  MUTEX_FAST..**.*
24830 2a 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f  * The other allo
24840 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74  wed parameters t
24850 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
24860 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74  alloc() each ret
24870 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  urn.** a pointer
24880 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65   to a static pre
24890 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20  existing mutex. 
248a0 20 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75 74   Four static mut
248b0 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  exes are.** used
248c0 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
248d0 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
248e0 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  e.  Future versi
248f0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
24900 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f   may add additio
24910 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78  nal static mutex
24920 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65  es.  Static mute
24930 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65  xes are for inte
24940 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53  rnal.** use by S
24950 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70  QLite only.  App
24960 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
24970 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65  se SQLite mutexe
24980 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20  s should.** use 
24990 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63  only the dynamic
249a0 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65   mutexes returne
249b0 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45  d by SQLITE_MUTE
249c0 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c  X_FAST or.** SQL
249d0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
249e0 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  IVE..**.** Note 
249f0 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74  that if one of t
24a00 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
24a10 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c   parameters (SQL
24a20 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a  ITE_MUTEX_FAST.*
24a30 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45  * or SQLITE_MUTE
24a40 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20  X_RECURSIVE) is 
24a50 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65  used then sqlite
24a60 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a  3_mutex_alloc().
24a70 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66  ** returns a dif
24a80 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20  ferent mutex on 
24a90 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 42 75 74  every call.  But
24aa0 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 20   for the static 
24ab0 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c  .** mutex types,
24ac0 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20   the same mutex 
24ad0 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65  is returned on e
24ae0 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68  very call that h
24af0 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  as.** the same t
24b00 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  ype number..**.*
24b10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  * The sqlite3_mu
24b20 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69  tex_free() routi
24b30 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ne deallocates a
24b40 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61   previously.** a
24b50 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63  llocated dynamic
24b60 20 6d 75 74 65 78 2e 20 20 53 51 4c 69 74 65 20   mutex.  SQLite 
24b70 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65  is careful to de
24b80 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a  allocate every.*
24b90 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  * dynamic mutex 
24ba0 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65  that it allocate
24bb0 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20  s.  The dynamic 
24bc0 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74  mutexes must not
24bd0 20 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65 20 77   be in .** use w
24be0 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61  hen they are dea
24bf0 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d  llocated.  Attem
24c00 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63  pting to dealloc
24c10 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20  ate a static.** 
24c20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e  mutex results in
24c30 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
24c40 69 6f 72 2e 20 20 53 51 4c 69 74 65 20 6e 65 76  ior.  SQLite nev
24c50 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a  er deallocates.*
24c60 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78  * a static mutex
24c70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24c80 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
24c90 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75  ) and sqlite3_mu
24ca0 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e  tex_try() routin
24cb0 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f  es attempt.** to
24cc0 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20   enter a mutex. 
24cd0 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
24ce0 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69  ad is already wi
24cf0 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a  thin the mutex,.
24d00 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
24d10 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c  _enter() will bl
24d20 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ock and sqlite3_
24d30 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c  mutex_try() will
24d40 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
24d50 45 5f 42 55 53 59 2e 20 20 54 68 65 20 73 71 6c  E_BUSY.  The sql
24d60 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
24d70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24d80 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20  ns SQLITE_OK.** 
24d90 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20  upon successful 
24da0 65 6e 74 72 79 2e 20 20 4d 75 74 65 78 65 73 20  entry.  Mutexes 
24db0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 53 51  created using SQ
24dc0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
24dd0 53 49 56 45 20 63 61 6e 0a 2a 2a 20 62 65 20 65  SIVE can.** be e
24de0 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  ntered multiple 
24df0 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d  times by the sam
24e00 65 20 74 68 72 65 61 64 2e 20 20 49 6e 20 73 75  e thread.  In su
24e10 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a  ch cases the,.**
24e20 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65   mutex must be e
24e30 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e  xited an equal n
24e40 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62  umber of times b
24e50 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68  efore another th
24e60 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65  read.** can ente
24e70 72 2e 20 20 49 66 20 74 68 65 20 73 61 6d 65 20  r.  If the same 
24e80 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20  thread tries to 
24e90 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 20  enter any other 
24ea0 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 0a 2a 2a  kind of mutex.**
24eb0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
24ec0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
24ed0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 20 53 51   undefined.   SQ
24ee0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
24ef0 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20  exhibit.** such 
24f00 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20  behavior in its 
24f10 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78  own use of mutex
24f20 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73  es..**.** Some s
24f30 79 73 74 65 6d 73 20 28 65 78 3a 20 77 69 6e 64  ystems (ex: wind
24f40 6f 77 73 39 35 29 20 64 6f 20 6e 6f 74 20 74 68  ows95) do not th
24f50 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 6d 70 6c  e operation impl
24f60 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 73 71  emented by.** sq
24f70 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
24f80 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73  ).  On those sys
24f90 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75  tems, sqlite3_mu
24fa0 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 0a 2a  tex_try() will.*
24fb0 2a 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  * always return 
24fc0 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54 68  SQLITE_BUSY.  Th
24fd0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e  e SQLite core on
24fe0 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20  ly ever uses.** 
24ff0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
25000 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69  y() as an optimi
25010 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69  zation so this i
25020 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68  s acceptable beh
25030 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  avior..**.** The
25040 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c   sqlite3_mutex_l
25050 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65  eave() routine e
25060 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 61  xits a mutex tha
25070 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  t was.** previou
25080 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74  sly entered by t
25090 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20  he same thread. 
250a0 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   The behavior.**
250b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66   is undefined if
250c0 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f   the mutex is no
250d0 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  t currently ente
250e0 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  red by the.** ca
250f0 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20  lling thread or 
25100 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
25110 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c   allocated.  SQL
25120 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65  ite will.** neve
25130 72 20 64 6f 20 65 69 74 68 65 72 2e 0a 2a 2a 0a  r do either..**.
25140 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
25150 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
25160 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
25170 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
25180 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75  ]..*/.sqlite3_mu
25190 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74  tex *sqlite3_mut
251a0 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  ex_alloc(int);.v
251b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
251c0 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d  x_free(sqlite3_m
251d0 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
251e0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
251f0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
25200 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  ;.int sqlite3_mu
25210 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f  tex_try(sqlite3_
25220 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
25230 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
25240 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  e(sqlite3_mutex*
25250 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25260 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 63  EF: Mutex Verifc
25270 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
25280 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
25290 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e  _mutex_held() an
252a0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
252b0 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e  notheld() routin
252c0 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64  es.** are intend
252d0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
252e0 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
252f0 6d 65 6e 74 73 2e 20 20 54 68 65 20 53 51 4c 69  ments.  The SQLi
25300 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72  te core.** never
25310 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74   uses these rout
25320 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69  ines except insi
25330 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61  de an assert() a
25340 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  nd applications.
25350 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74  ** are advised t
25360 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61  o follow the lea
25370 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20  d of the core.  
25380 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a  The core only.**
25390 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d   provides implem
253a0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  entations for th
253b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65  ese routines whe
253c0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
253d0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c  .** with the SQL
253e0 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20  ITE_DEBUG flag. 
253f0 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   External mutex 
25400 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
25410 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 75  ** are only requ
25420 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20  ired to provide 
25430 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
25440 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 69  f SQLITE_DEBUG i
25450 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e 64  s.** defined and
25460 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e 6f   if NDEBUG is no
25470 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  t defined..**.**
25480 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
25490 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72  should return tr
254a0 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 78 20  ue if the mutex 
254b0 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e  in their argumen
254c0 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20  t.** is held or 
254d0 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63  not held, respec
254e0 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63  tively, by the c
254f0 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a  alling thread..*
25500 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65  *.** The impleme
25510 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72  ntation is not r
25520 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69  equired to provi
25530 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ded versions of 
25540 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  these.** routine
25550 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20  s that actually 
25560 77 6f 72 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20  work..** If the 
25570 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64  implementation d
25580 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20  oes not provide 
25590 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69  working.** versi
255a0 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ons of these rou
255b0 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64  tines, it should
255c0 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64   at least provid
255d0 65 20 73 74 75 62 73 0a 2a 2a 20 74 68 61 74 20  e stubs.** that 
255e0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 72  always return tr
255f0 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64  ue so that one d
25600 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72  oes not get spur
25610 69 6f 75 73 0a 2a 2a 20 61 73 73 65 72 74 69 6f  ious.** assertio
25620 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a  n failures..**.*
25630 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e  * If the argumen
25640 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  t to sqlite3_mut
25650 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61 20 4e  ex_held() is a N
25660 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
25670 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20  .** the routine 
25680 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 2e  should return 1.
25690 20 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75    This seems cou
256a0 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73  nter-intuitive s
256b0 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20  ince.** clearly 
256c0 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74  the mutex cannot
256d0 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64   be held if it d
256e0 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20  oes not exist.  
256f0 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72  But the.** the r
25700 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20  eason the mutex 
25710 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69  does not exist i
25720 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75  s because the bu
25730 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73  ild is not.** us
25740 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e  ing mutexes.  An
25750 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74  d we do not want
25760 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f   the assert() co
25770 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
25780 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
25790 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20  mutex_held() to 
257a0 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a  fail, so a non-z
257b0 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a  ero return is.**
257c0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
257d0 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 54   thing to do.  T
257e0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
257f0 5f 6e 6f 74 68 65 6c 64 28 29 20 0a 2a 2a 20 69  _notheld() .** i
25800 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20  nterface should 
25810 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77 68  also return 1 wh
25820 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20  en given a NULL 
25830 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20  pointer..*/.int 
25840 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
25850 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ld(sqlite3_mutex
25860 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
25870 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71  mutex_notheld(sq
25880 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a  lite3_mutex*);..
25890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
258a0 4d 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a  Mutex Types.**.*
258b0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
258c0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e  utex_alloc()] in
258d0 74 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20  terface takes a 
258e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a  single argument.
258f0 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20  ** which is one 
25900 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
25910 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2f 0a 23   constants..*/.#
25920 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
25930 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20  TEX_FAST        
25940 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
25950 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
25960 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23  RSIVE        1.#
25970 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
25980 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
25990 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  R    2.#define S
259a0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
259b0 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20  IC_MEM       3  
259c0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  /* sqlite3_mallo
259d0 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  c() */.#define S
259e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
259f0 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20  IC_MEM2      4  
25a00 2f 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  /* sqlite3_relea
25a10 73 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a 23  se_memory() */.#
25a20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
25a30 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20  TEX_STATIC_PRNG 
25a40 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
25a50 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23  e3_random() */.#
25a60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
25a70 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20  TEX_STATIC_LRU  
25a80 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70       6  /* lru p
25a90 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a  age list */../*.
25aa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77  ** CAPI3REF: Low
25ab0 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f  -Level Control O
25ac0 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73  f Database Files
25ad0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
25ae0 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
25af0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61  ()] interface ma
25b00 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61 6c  kes a direct cal
25b10 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c  l to the.** xFil
25b20 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
25b30 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
25b40 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
25b50 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  ect associated.*
25b60 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  * with a particu
25b70 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64 65  lar database ide
25b80 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
25b90 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20  econd argument. 
25ba0 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20   The.** name of 
25bb0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
25bc0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
25bd0 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  d to the databas
25be0 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 68  e by the.** <a h
25bf0 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68  ref="lang_attach
25c00 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61  .html">ATTACH</a
25c10 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 68  > SQL command th
25c20 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a 2a  at opened the.**
25c30 20 64 61 74 61 62 61 73 65 2e 20 20 54 6f 20 63   database.  To c
25c40 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20  ontrol the main 
25c50 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 75  database file, u
25c60 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69  se the name "mai
25c70 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20  n".** or a NULL 
25c80 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 74 68  pointer.  The th
25c90 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
25ca0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
25cb0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65  s routine.** are
25cc0 20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c 79   passed directly
25cd0 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
25ce0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
25cf0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a   parameters of.*
25d00 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * the xFileContr
25d10 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 54 68 65 20  ol method.  The 
25d20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
25d30 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
25d40 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d  .** method becom
25d50 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  es the return va
25d60 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74  lue of this rout
25d70 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ine..**.** If th
25d80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
25d90 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f 65  er (zDbName) doe
25da0 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65 20  s not match the 
25db0 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  name of any.** o
25dc0 70 65 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  pen database fil
25dd0 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 45  e, then SQLITE_E
25de0 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65 64  RROR is returned
25df0 2e 20 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a  .  This error.**
25e00 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d   code is not rem
25e10 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c  embered and will
25e20 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64   not be recalled
25e30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   by [sqlite3_err
25e40 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  code()].** or [s
25e50 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
25e60 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
25e70 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  g xFileControl m
25e80 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20 61  ethod might.** a
25e90 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49 54  lso return SQLIT
25ea0 45 5f 45 52 52 4f 52 2e 20 20 54 68 65 72 65 20  E_ERROR.  There 
25eb0 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73  is no way to dis
25ec0 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e  tinguish between
25ed0 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74  .** an incorrect
25ee0 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20   zDbName and an 
25ef0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74  SQLITE_ERROR ret
25f00 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64  urn from the und
25f10 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65  erlying.** xFile
25f20 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 0a  Control method..
25f30 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
25f40 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
25f50 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74 20  CKSTATE].*/.int 
25f60 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
25f70 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20 63  trol(sqlite3*, c
25f80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
25f90 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  me, int op, void
25fa0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20  *);../*.** Undo 
25fb0 74 68 65 20 68 61 63 6b 20 74 68 61 74 20 63 6f  the hack that co
25fc0 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 6e 67 20  nverts floating 
25fd0 70 6f 69 6e 74 20 74 79 70 65 73 20 74 6f 20 69  point types to i
25fe0 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75  nteger for.** bu
25ff0 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f  ilds on processo
26000 72 73 20 77 69 74 68 6f 75 74 20 66 6c 6f 61 74  rs without float
26010 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
26020 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  t..*/.#ifdef SQL
26030 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e  ITE_OMIT_FLOATIN
26040 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20  G_POINT.# undef 
26050 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23  double.#endif..#
26060 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75  ifdef __cplusplu
26070 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74  s.}  /* End of t
26080 68 65 20 27 65 78 74 65 72 6e 20 22 43 22 27 20  he 'extern "C"' 
26090 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a  block */.#endif.
260a0 23 65 6e 64 69 66 0a                             #endif.