/ Hex Artifact Content
Login

Artifact 26b53ebd71d051bdefb6ba326f6742747c188cb7:


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 31 20 32 30 30 37 2f  in,v 1.261 2007/
05f0: 30 39 2f 31 37 20 30 37 3a 30 32 3a 35 37 20 64  09/17 07:02:57 d
0600: 61 6e 69 65 6c 6b 31 39 37 37 20 45 78 70 20 24  anielk1977 Exp $
0610: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
0620: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
0630: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0640: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0650: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0660: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0670: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0680: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0690: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
06a0: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
06b0: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
06c0: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
06d0: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06e0: 2a 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69  ** Add the abili
06f0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27  ty to override '
0700: 65 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64  extern'.*/.#ifnd
0710: 65 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  ef SQLITE_EXTERN
0720: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
0730: 5f 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23  _EXTERN extern.#
0740: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  endif../*.** Mak
0750: 65 20 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  e sure these sym
0760: 62 6f 6c 73 20 77 68 65 72 65 20 6e 6f 74 20 64  bols where not d
0770: 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70  efined by some p
0780: 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 0a 2a  revious header.*
0790: 2a 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  * file..*/.#ifde
07a0: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
07b0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
07c0: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
07d0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
07e0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
07f0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0800: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0810: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0820: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0830: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0840: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  umbers.**.** The
0850: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
0860: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69  SQLite library i
0870: 73 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  s contained in t
0880: 68 65 20 73 71 6c 69 74 65 33 2e 68 0a 2a 2a 20  he sqlite3.h.** 
0890: 68 65 61 64 65 72 20 66 69 6c 65 20 69 6e 20 61  header file in a
08a0: 20 23 64 65 66 69 6e 65 20 6e 61 6d 65 64 20 53   #define named S
08b0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 2e 20 20  QLITE_VERSION.  
08c0: 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  The SQLITE_VERSI
08d0: 4f 4e 0a 2a 2a 20 6d 61 63 72 6f 20 72 65 73 6f  ON.** macro reso
08e0: 6c 76 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67  lves to a string
08f0: 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a   constant..**.**
0900: 20 54 68 65 20 66 6f 72 6d 61 74 20 6f 66 20 74   The format of t
0910: 68 65 20 76 65 72 73 69 6f 6e 20 73 74 72 69 6e  he version strin
0920: 67 20 69 73 20 22 58 2e 59 2e 5a 22 2c 20 77 68  g is "X.Y.Z", wh
0930: 65 72 65 0a 2a 2a 20 58 20 69 73 20 74 68 65 20  ere.** X is the 
0940: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75  major version nu
0950: 6d 62 65 72 2c 20 59 20 69 73 20 74 68 65 20 6d  mber, Y is the m
0960: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0970: 62 65 72 20 61 6e 64 20 5a 0a 2a 2a 20 69 73 20  ber and Z.** is 
0980: 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62  the release numb
0990: 65 72 2e 20 20 54 68 65 20 58 2e 59 2e 5a 20 6d  er.  The X.Y.Z m
09a0: 69 67 68 74 20 62 65 20 66 6f 6c 6c 6f 77 65 64  ight be followed
09b0: 20 62 79 20 22 61 6c 70 68 61 22 20 6f 72 20 22   by "alpha" or "
09c0: 62 65 74 61 22 2e 0a 2a 2a 20 46 6f 72 20 65 78  beta"..** For ex
09d0: 61 6d 70 6c 65 20 22 33 2e 31 2e 31 62 65 74 61  ample "3.1.1beta
09e0: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 58 20 76  "..**.** The X v
09f0: 61 6c 75 65 20 69 73 20 61 6c 77 61 79 73 20 33  alue is always 3
0a00: 20 69 6e 20 53 51 4c 69 74 65 2e 20 20 54 68 65   in SQLite.  The
0a10: 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68   X value only ch
0a20: 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20 62 61  anges when.** ba
0a30: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
0a40: 69 6c 69 74 79 20 69 73 20 62 72 6f 6b 65 6e 20  ility is broken 
0a50: 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 74 6f  and we intend to
0a60: 20 6e 65 76 65 72 20 62 72 65 61 6b 0a 2a 2a 20   never break.** 
0a70: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0a80: 69 62 69 6c 69 74 79 2e 20 20 54 68 65 20 59 20  ibility.  The Y 
0a90: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0aa0: 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65  es when.** there
0ab0: 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 75   are major featu
0ac0: 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20  re enhancements 
0ad0: 74 68 61 74 20 61 72 65 20 66 6f 72 77 61 72 64  that are forward
0ae0: 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20  s compatible.** 
0af0: 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 64  but not backward
0b00: 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 20 20 54  s compatible.  T
0b10: 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20 69 6e  he Z value is in
0b20: 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a  cremented with.*
0b30: 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65 20 62  * each release b
0b40: 75 74 20 72 65 73 65 74 73 20 62 61 63 6b 20 74  ut resets back t
0b50: 6f 20 30 20 77 68 65 6e 20 59 20 69 73 20 69 6e  o 0 when Y is in
0b60: 63 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  cremented..**.**
0b70: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53   The SQLITE_VERS
0b80: 49 4f 4e 5f 4e 55 4d 42 45 52 20 69 73 20 61 6e  ION_NUMBER is an
0b90: 20 69 6e 74 65 67 65 72 20 77 69 74 68 20 74 68   integer with th
0ba0: 65 20 76 61 6c 75 65 20 0a 2a 2a 20 28 58 2a 31  e value .** (X*1
0bb0: 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20  000000 + Y*1000 
0bc0: 2b 20 5a 29 2e 20 46 6f 72 20 65 78 61 6d 70 6c  + Z). For exampl
0bd0: 65 2c 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 22  e, for version "
0be0: 33 2e 31 2e 31 62 65 74 61 22 2c 20 0a 2a 2a 20  3.1.1beta", .** 
0bf0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0c00: 55 4d 42 45 52 20 69 73 20 73 65 74 20 74 6f 20  UMBER is set to 
0c10: 33 30 30 31 30 30 31 2e 20 54 6f 20 64 65 74 65  3001001. To dete
0c20: 63 74 20 69 66 20 74 68 65 79 20 61 72 65 20 75  ct if they are u
0c30: 73 69 6e 67 20 0a 2a 2a 20 76 65 72 73 69 6f 6e  sing .** version
0c40: 20 33 2e 31 2e 31 20 6f 72 20 67 72 65 61 74 65   3.1.1 or greate
0c50: 72 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  r at compile tim
0c60: 65 2c 20 70 72 6f 67 72 61 6d 73 20 6d 61 79 20  e, programs may 
0c70: 75 73 65 20 74 68 65 20 74 65 73 74 20 0a 2a 2a  use the test .**
0c80: 20 28 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   (SQLITE_VERSION
0c90: 5f 4e 55 4d 42 45 52 3e 3d 33 30 30 31 30 30 31  _NUMBER>=3001001
0ca0: 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
0cb0: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
0cc0: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
0cd0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
0ce0: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2f 0a  n_number()]..*/.
0cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0d00: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 20 22  ERSION         "
0d10: 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e  --VERS--".#defin
0d20: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0d30: 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f  _NUMBER --VERSIO
0d40: 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a  N-NUMBER--../*.*
0d50: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
0d60: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
0d70: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a  sion Numbers.**.
0d80: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
0d90: 73 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20  s return values 
0da0: 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 74 68  equivalent to th
0db0: 65 20 68 65 61 64 65 72 20 63 6f 6e 73 74 61 6e  e header constan
0dc0: 74 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ts.** [SQLITE_VE
0dd0: 52 53 49 4f 4e 5d 20 61 6e 64 20 5b 53 51 4c 49  RSION] and [SQLI
0de0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0df0: 52 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  R].  The values 
0e00: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74  returned.** by t
0e10: 68 69 73 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  his routines sho
0e20: 75 6c 64 20 6f 6e 6c 79 20 62 65 20 64 69 66 66  uld only be diff
0e30: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 68  erent from the h
0e40: 65 61 64 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  eader values.** 
0e50: 69 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65 20 79  if you compile y
0e60: 6f 75 72 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  our program usin
0e70: 67 20 61 6e 20 73 71 6c 69 74 65 33 2e 68 20 68  g an sqlite3.h h
0e80: 65 61 64 65 72 20 66 72 6f 6d 20 61 0a 2a 2a 20  eader from a.** 
0e90: 64 69 66 66 65 72 65 6e 74 20 76 65 72 73 69 6f  different versio
0ea0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
0eb0: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   the version of 
0ec0: 74 68 65 20 6c 69 62 72 61 72 79 20 79 6f 75 0a  the library you.
0ed0: 2a 2a 20 6c 69 6e 6b 20 61 67 61 69 6e 73 74 2e  ** link against.
0ee0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
0ef0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
0f00: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
0f10: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
0f20: 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
0f30: 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67  _VERSION] string
0f40: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
0f50: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
0f60: 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20  tion returns.** 
0f70: 61 20 70 6f 69 6e 65 72 20 74 6f 20 74 68 65 20  a poiner to the 
0f80: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
0f90: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
0fa0: 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
0fb0: 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20  .** is provided 
0fc0: 66 6f 72 20 44 4c 4c 20 75 73 65 72 73 20 77 68  for DLL users wh
0fd0: 6f 20 63 61 6e 20 6f 6e 6c 79 20 61 63 63 65 73  o can only acces
0fe0: 73 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  s functions and 
0ff0: 6e 6f 74 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73  not.** constants
1000: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e   within the DLL.
1010: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
1020: 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c  N const char sql
1030: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a  ite3_version[];.
1040: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1050: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76  te3_libversion(v
1060: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
1070: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
1080: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ber(void);../*.*
1090: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
10a0: 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c   To See If The L
10b0: 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64  ibrary Is Thread
10c0: 73 61 66 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  safe.**.** This 
10d0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10e0: 54 52 55 45 20 28 6e 6f 6e 7a 65 72 6f 29 20 69  TRUE (nonzero) i
10f0: 66 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d  f SQLite was com
1100: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 61 6c  piled with.** al
1110: 6c 20 6f 66 20 69 74 73 20 6d 75 74 65 78 65 73  l of its mutexes
1120: 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 69 73 20   enabled and is 
1130: 74 68 75 73 20 74 68 72 65 61 64 73 61 66 65 2e  thus threadsafe.
1140: 20 20 49 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20    It returns.** 
1150: 7a 65 72 6f 20 69 66 20 74 68 65 20 70 61 72 74  zero if the part
1160: 69 63 75 6c 61 72 20 62 75 69 6c 64 20 69 73 20  icular build is 
1170: 66 6f 72 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  for single-threa
1180: 64 65 64 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  ded operation.**
1190: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 61   only..**.** Rea
11a0: 6c 6c 79 20 61 6c 6c 20 74 68 69 73 20 72 6f 75  lly all this rou
11b0: 74 69 6e 65 20 64 6f 65 73 20 69 73 20 72 65 74  tine does is ret
11c0: 75 72 6e 20 74 72 75 65 20 69 66 20 53 51 4c 69  urn true if SQLi
11d0: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a  te was compiled.
11e0: 2a 2a 20 77 69 74 68 20 74 68 65 20 2d 44 53 51  ** with the -DSQ
11f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1200: 31 20 6f 70 74 69 6f 6e 20 61 6e 64 20 66 61 6c  1 option and fal
1210: 73 65 20 69 66 0a 2a 2a 20 63 6f 6d 70 69 6c 65  se if.** compile
1220: 64 20 77 69 74 68 20 2d 44 53 51 4c 49 54 45 5f  d with -DSQLITE_
1230: 54 48 52 45 41 44 53 41 46 45 3d 30 2e 20 20 49  THREADSAFE=0.  I
1240: 66 20 53 51 4c 69 74 65 20 75 73 65 73 20 61 6e  f SQLite uses an
1250: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  .** application-
1260: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 73 75  defined mutex su
1270: 62 73 79 73 74 65 6d 2c 20 6d 61 6c 6c 6f 63 20  bsystem, malloc 
1280: 73 75 62 73 79 73 74 65 6d 2c 20 63 6f 6c 6c 61  subsystem, colla
1290: 74 69 6e 67 0a 2a 2a 20 73 65 71 75 65 6e 63 65  ting.** sequence
12a0: 2c 20 56 46 53 2c 20 53 51 4c 20 66 75 6e 63 74  , VFS, SQL funct
12b0: 69 6f 6e 2c 20 70 72 6f 67 72 65 73 73 20 63 61  ion, progress ca
12c0: 6c 6c 62 61 63 6b 2c 20 63 6f 6d 6d 69 74 20 68  llback, commit h
12d0: 6f 6f 6b 2c 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ook,.** extensio
12e0: 6e 2c 20 6f 72 20 6f 74 68 65 72 20 61 63 63 65  n, or other acce
12f0: 73 73 6f 72 69 65 73 20 61 6e 64 20 74 68 65 73  ssories and thes
1300: 65 20 61 64 64 2d 6f 6e 73 20 61 72 65 20 6e 6f  e add-ons are no
1310: 74 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 65 2c  t.** threadsafe,
1320: 20 74 68 65 6e 20 63 6c 65 61 72 6c 79 20 74 68   then clearly th
1330: 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 77 69  e combination wi
1340: 6c 6c 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ll not be thread
1350: 73 61 66 65 0a 2a 2a 20 65 69 74 68 65 72 2e 20  safe.** either. 
1360: 20 48 65 6e 63 65 2c 20 74 68 69 73 20 72 6f 75   Hence, this rou
1370: 74 69 6e 65 20 6e 65 76 65 72 20 72 65 70 6f 72  tine never repor
1380: 74 73 20 74 68 61 74 20 74 68 65 20 6c 69 62 72  ts that the libr
1390: 61 72 79 0a 2a 2a 20 69 73 20 67 75 61 72 61 6e  ary.** is guaran
13a0: 74 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  teed to be threa
13b0: 64 73 61 66 65 2c 20 6f 6e 6c 79 20 77 68 65 6e  dsafe, only when
13c0: 20 69 74 20 69 73 20 67 75 61 72 61 6e 74 65 65   it is guarantee
13d0: 64 20 6e 6f 74 0a 2a 2a 20 74 6f 20 62 65 2e 0a  d not.** to be..
13e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 6e  **.** This is an
13f0: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 41 50   experimental AP
1400: 49 20 61 6e 64 20 6d 61 79 20 67 6f 20 61 77 61  I and may go awa
1410: 79 20 6f 72 20 63 68 61 6e 67 65 20 69 6e 20 66  y or change in f
1420: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
1430: 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
1440: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
1450: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
1460: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
1470: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
1480: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
1490: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
14a0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
14b0: 79 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  y pointer to an 
14c0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a  instance of the.
14d0: 2a 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  ** opaque struct
14e0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
14f0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1500: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1510: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1520: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1530: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
1540: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1550: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1560: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
1570: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1580: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
1590: 74 72 75 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20  tructors.** and 
15a0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
15b0: 5d 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63  ] is its destruc
15c0: 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20  tor.  There are 
15d0: 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72  many other inter
15e0: 66 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 61  faces.** (such a
15f0: 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1600: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
1610: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1620: 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  on()], and.** [s
1630: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1640: 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62  out()] to name b
1650: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61  ut three) that a
1660: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68  re methods on th
1670: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f  is.** object..*/
1680: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1690: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
16a0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
16b0: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
16c0: 72 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 53 6f  r Types.**.** So
16d0: 6d 65 20 63 6f 6d 70 69 6c 65 72 73 20 64 6f 20  me compilers do 
16e0: 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65 20  not support the 
16f0: 22 6c 6f 6e 67 20 6c 6f 6e 67 22 20 64 61 74 61  "long long" data
1700: 74 79 70 65 2e 20 20 53 6f 20 77 65 20 68 61 76  type.  So we hav
1710: 65 0a 2a 2a 20 74 6f 20 64 6f 20 63 6f 6d 70 69  e.** to do compi
1720: 6c 65 72 2d 73 70 65 63 69 66 69 63 20 74 79 70  ler-specific typ
1730: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
1740: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
1750: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
1760: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
1770: 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1780: 69 6f 6e 73 20 72 65 71 75 69 72 65 20 61 20 36  ions require a 6
1790: 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 61 72  4-bit integer ar
17a0: 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 6f 73  guments..** Thos
17b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
17c0: 20 64 65 63 6c 61 72 65 64 20 75 73 69 6e 67 20   declared using 
17d0: 74 68 69 73 20 74 79 70 65 64 65 66 2e 0a 2a 2f  this typedef..*/
17e0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49  .#ifdef SQLITE_I
17f0: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65  NT64_TYPE.  type
1800: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
1810: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74  _TYPE sqlite_int
1820: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
1830: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e  signed SQLITE_IN
1840: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
1850: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65  uint64;.#elif de
1860: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20  fined(_MSC_VER) 
1870: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52  || defined(__BOR
1880: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64  LANDC__).  typed
1890: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ef __int64 sqlit
18a0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
18b0: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e  ef unsigned __in
18c0: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  t64 sqlite_uint6
18d0: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64  4;.#else.  typed
18e0: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ef long long int
18f0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
1900: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
1910: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  d long long int 
1920: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
1930: 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71  endif.typedef sq
1940: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
1950: 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65  e3_int64;.typede
1960: 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  f sqlite_uint64 
1970: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a  sqlite3_uint64;.
1980: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c  ./*.** If compil
1990: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73  ing for a proces
19a0: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66  sor that lacks f
19b0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75  loating point su
19c0: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69  pport,.** substi
19d0: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72  tute integer for
19e0: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 0a   floating-point.
19f0: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
1a00: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
1a10: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f  OINT.# define do
1a20: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  uble sqlite3_int
1a30: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  64.#endif../*.**
1a40: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69   CAPI3REF: Closi
1a50: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  ng A Database Co
1a60: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 43  nnection.**.** C
1a70: 61 6c 6c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  all this functio
1a80: 6e 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  n with a pointer
1a90: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
1aa0: 74 68 61 74 20 77 61 73 20 70 72 65 76 69 6f 75  that was previou
1ab0: 73 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  sly.** returned 
1ac0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
1ad0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1ae0: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
1af0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1b00: 32 28 29 5d 20 61 6e 64 20 74 68 65 20 63 6f 72  2()] and the cor
1b10: 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 62  responding datab
1b20: 61 73 65 20 77 69 6c 6c 20 62 79 0a 2a 2a 20 63  ase will by.** c
1b30: 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c  losed..**.** All
1b40: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1b50: 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 5b  prepared using [
1b60: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1b70: 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
1b80: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1b90: 32 28 29 5d 20 6d 75 73 74 20 62 65 20 64 65 73  2()] must be des
1ba0: 74 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 71  troyed using [sq
1bb0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1bc0: 5d 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  ].** before this
1bd0: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
1be0: 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 53  ed. Otherwise, S
1bf0: 51 4c 49 54 45 5f 42 55 53 59 20 69 73 20 72 65  QLITE_BUSY is re
1c00: 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 0a 2a  turned and the.*
1c10: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1c20: 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 6f 70  ction remains op
1c30: 65 6e 2e 0a 2a 2a 0a 2a 2a 20 50 61 73 73 69 6e  en..**.** Passin
1c40: 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  g this routine a
1c50: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c60: 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 61 6c  tion that has al
1c70: 72 65 61 64 79 20 62 65 65 6e 0a 2a 2a 20 63 6c  ready been.** cl
1c80: 6f 73 65 64 20 72 65 73 75 6c 74 73 20 69 6e 20  osed results in 
1c90: 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1ca0: 6f 72 2e 20 20 49 66 20 6f 74 68 65 72 20 69 6e  or.  If other in
1cb0: 74 65 72 66 61 63 65 73 20 74 68 61 74 0a 2a 2a  terfaces that.**
1cc0: 20 72 65 66 65 72 65 6e 63 65 20 74 68 65 20 73   reference the s
1cd0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1ce0: 6e 65 63 74 69 6f 6e 20 61 72 65 20 70 65 6e 64  nection are pend
1cf0: 69 6e 67 20 28 65 69 74 68 65 72 20 69 6e 20 74  ing (either in t
1d00: 68 65 0a 2a 2a 20 73 61 6d 65 20 74 68 72 65 61  he.** same threa
1d10: 64 20 6f 72 20 69 6e 20 64 69 66 66 65 72 65 6e  d or in differen
1d20: 74 20 74 68 72 65 61 64 73 29 20 77 68 65 6e 20  t threads) when 
1d30: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
1d40: 63 61 6c 6c 65 64 2c 0a 2a 2a 20 74 68 65 6e 20  called,.** then 
1d50: 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1d60: 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 69 73  undefined and is
1d70: 20 61 6c 6d 6f 73 74 20 63 65 72 74 61 69 6e 6c   almost certainl
1d80: 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
1d90: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
1da0: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a  ose(sqlite3 *);.
1db0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
1dc0: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
1dd0: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
1de0: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
1df0: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
1e00: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
1e10: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
1e20: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
1e30: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
1e40: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
1e50: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
1e60: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
1e70: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
1e80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e90: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
1ea0: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
1eb0: 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ace.**.** This i
1ec0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
1ed0: 20 74 6f 20 64 6f 20 61 20 6f 6e 65 2d 74 69 6d   to do a one-tim
1ee0: 65 20 65 76 61 6c 75 61 74 61 74 69 6f 6e 20 6f  e evaluatation o
1ef0: 66 20 7a 65 72 6f 0a 2a 2a 20 6f 72 20 6d 6f 72  f zero.** or mor
1f00: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1f10: 2e 20 20 55 54 46 2d 38 20 74 65 78 74 20 6f 66  .  UTF-8 text of
1f20: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1f30: 6e 74 73 20 74 6f 0a 2a 2a 20 62 65 20 65 76 61  nts to.** be eva
1f40: 6c 75 74 65 64 20 69 73 20 70 61 73 73 65 64 20  luted is passed 
1f50: 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  in as the second
1f60: 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
1f70: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
1f80: 72 65 20 70 72 65 70 61 72 65 64 20 6f 6e 65 20  re prepared one 
1f90: 62 79 20 6f 6e 65 20 75 73 69 6e 67 20 5b 73 71  by one using [sq
1fa0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1fb0: 2c 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 75  , evaluated.** u
1fc0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
1fd0: 65 70 28 29 5d 2c 20 74 68 65 6e 20 64 65 73 74  ep()], then dest
1fe0: 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  royed using [sql
1ff0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2000: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 6e 65 20 6f  ..**.** If one o
2010: 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 51  r more of the SQ
2020: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
2030: 20 71 75 65 72 69 65 73 2c 20 74 68 65 6e 0a 2a   queries, then.*
2040: 2a 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * the callback f
2050: 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  unction specifie
2060: 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72  d by the 3rd par
2070: 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 69 6e 76  ameter is.** inv
2080: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  oked once for ea
2090: 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 71 75  ch row of the qu
20a0: 65 72 79 20 72 65 73 75 6c 74 2e 20 20 54 68 69  ery result.  Thi
20b0: 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 73 68  s callback.** sh
20c0: 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20 72 65  ould normally re
20d0: 74 75 72 6e 20 30 2e 20 20 49 66 20 74 68 65 20  turn 0.  If the 
20e0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20f0: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 76   a non-zero.** v
2100: 61 6c 75 65 20 74 68 65 6e 20 74 68 65 20 71 75  alue then the qu
2110: 65 72 79 20 69 73 20 61 62 6f 72 74 65 64 2c 20  ery is aborted, 
2120: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53  all subsequent S
2130: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2140: 20 61 72 65 20 73 6b 69 70 70 65 64 20 61 6e 64   are skipped and
2150: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
2160: 63 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  c() function ret
2170: 75 72 6e 73 20 74 68 65 20 5b 53 51 4c 49 54 45  urns the [SQLITE
2180: 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _ABORT]..**.** T
2190: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
21a0: 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61   to this interfa
21b0: 63 65 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  ce is an arbitra
21c0: 72 79 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ry pointer that 
21d0: 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
21e0: 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
21f0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61 73  back function as
2200: 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d   its first param
2210: 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eter..**.** The 
2220: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
2230: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
2240: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6e 75  nction is the nu
2250: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 6f 6c 75 6d  mber of.** colum
2260: 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
2270: 72 65 73 75 6c 74 2e 20 20 54 68 65 20 33 72 64  result.  The 3rd
2280: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2290: 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  e callback.** is
22a0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74 72   an array of str
22b0: 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65  ings holding the
22c0: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68   values for each
22d0: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 73 20 65 78   column.** as ex
22e0: 74 72 61 63 74 65 64 20 75 73 69 6e 67 20 5b 73  tracted using [s
22f0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2300: 78 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 34 74  xt()]..** The 4t
2310: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2320: 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
2330: 6e 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e  n array of strin
2340: 67 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 75  gs.** obtained u
2350: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
2360: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64  lumn_name()] and
2370: 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 74 68 65 20   holding.** the 
2380: 6e 61 6d 65 73 20 6f 66 20 65 61 63 68 20 63 6f  names of each co
2390: 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lumn..**.** The 
23a0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
23b0: 6e 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 65  n may be NULL, e
23c0: 76 65 6e 20 66 6f 72 20 71 75 65 72 69 65 73 2e  ven for queries.
23d0: 20 20 41 20 4e 55 4c 4c 0a 2a 2a 20 63 61 6c 6c    A NULL.** call
23e0: 62 61 63 6b 20 69 73 20 6e 6f 74 20 61 6e 20 65  back is not an e
23f0: 72 72 6f 72 2e 20 20 49 74 20 6a 75 73 74 20 6d  rror.  It just m
2400: 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 63 61 6c  eans that no cal
2410: 6c 62 61 63 6b 0a 2a 2a 20 77 69 6c 6c 20 62 65  lback.** will be
2420: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
2430: 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
2440: 72 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67  rs while parsing
2450: 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 74   or evaluating t
2460: 68 65 20 53 51 4c 20 28 62 75 74 0a 2a 2a 20 6e  he SQL (but.** n
2470: 6f 74 20 77 68 69 6c 65 20 65 78 65 63 75 74 69  ot while executi
2480: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 29  ng the callback)
2490: 20 74 68 65 6e 20 61 6e 20 61 70 70 72 6f 70 72   then an appropr
24a0: 69 61 74 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65  iate error.** me
24b0: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
24c0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
24d0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
24e0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
24f0: 64 0a 2a 2a 20 2a 65 72 72 6d 73 67 20 69 73 20  d.** *errmsg is 
2500: 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2510: 20 74 68 61 74 20 6d 65 73 73 61 67 65 2e 20 20   that message.  
2520: 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
2530: 74 69 6f 6e 0a 2a 2a 20 69 73 20 72 65 73 70 6f  tion.** is respo
2540: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
2550: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 75 73  ng the memory us
2560: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
2570: 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 65 72 72 6d  e()]..** If errm
2580: 73 67 3d 3d 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e  sg==NULL, then n
2590: 6f 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  o error message 
25a0: 69 73 20 65 76 65 72 20 77 72 69 74 74 65 6e 2e  is ever written.
25b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  .**.** The retur
25c0: 6e 20 76 61 6c 75 65 20 69 73 20 69 73 20 53 51  n value is is SQ
25d0: 4c 49 54 45 5f 4f 4b 20 69 66 20 74 68 65 72 65  LITE_OK if there
25e0: 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 20 61   are no errors a
25f0: 6e 64 0a 2a 2a 20 73 6f 6d 65 20 6f 74 68 65 72  nd.** some other
2600: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
2610: 74 75 72 6e 20 63 6f 64 65 5d 20 69 66 20 74 68  turn code] if th
2620: 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  ere is an error.
2630: 20 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63    .** The partic
2640: 75 6c 61 72 20 72 65 74 75 72 6e 20 76 61 6c 75  ular return valu
2650: 65 20 64 65 70 65 6e 64 73 20 6f 6e 20 74 68 65  e depends on the
2660: 20 74 79 70 65 20 6f 66 20 65 72 72 6f 72 2e 20   type of error. 
2670: 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  .**.*/.int sqlit
2680: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
2690: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
26a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26b0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
26c0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
26d0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
26e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
2700: 20 74 6f 20 62 65 20 65 76 61 6c 75 74 65 64 20   to be evaluted 
2710: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
2720: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
2730: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
2740: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
2750: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
2760: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2770: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2780: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
2790: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
27a0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
27b0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
27c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27d0: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
27e0: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
27f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2800: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
2810: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
2820: 54 45 5f 4f 4b 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  TE_OK.**.** Many
2830: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
2840: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
2850: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
2860: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
2870: 77 6e 0a 2a 2a 20 61 62 6f 76 65 20 69 6e 20 6f  wn.** above in o
2880: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
2890: 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  s success or fai
28a0: 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lure..**.** The 
28b0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 62 6f  result codes abo
28c0: 76 65 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ve are the only 
28d0: 6f 6e 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  ones returned by
28e0: 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 0a 2a   SQLite in its.*
28f0: 2a 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  * default config
2900: 75 72 61 74 69 6f 6e 2e 20 20 48 6f 77 65 76 65  uration.  Howeve
2910: 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  r, the [sqlite3_
2920: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
2930: 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 41 50 49 20  codes()].** API 
2940: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73  can be used to s
2950: 65 74 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  et a database co
2960: 6e 6e 65 63 74 6f 69 6e 20 74 6f 20 72 65 74 75  nnectoin to retu
2970: 72 6e 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  rn more detailed
2980: 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 64 65 73  .** result codes
2990: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
29a0: 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  : [SQLITE_IOERR_
29b0: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
29c0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2a  result codes].**
29d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
29e0: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
29f0: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
2a00: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
2a10: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
2a20: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
2a30: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
2a40: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
2a50: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
2a60: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
2a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2a80: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
2a90: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 49 6e 74 65  * NOT USED. Inte
2aa0: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
2ab0: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
2ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
2ad0: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
2ae0: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
2af0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
2b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
2b10: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
2b20: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
2b30: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
2b40: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
2b50: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
2b60: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
2b70: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
2b80: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
2b90: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
2ba0: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
2bb0: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
2bc0: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
2bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2be0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
2bf0: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
2c00: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
2c10: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
2c20: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
2c30: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
2c40: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
2c50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2c60: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
2c70: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
2c80: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
2c90: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
2ca0: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ()*/.#define SQL
2cb0: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
2cc0: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
2cd0: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
2ce0: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
2cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
2d00: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
2d10: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
2d20: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
2d30: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
2d40: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
2d50: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f  ND    12   /* NO
2d60: 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72  T USED. Table or
2d70: 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e   record not foun
2d80: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
2d90: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
2da0: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
2db0: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
2dc0: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
2dd0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
2de0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
2df0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
2e00: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
2e10: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
2e20: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
2e30: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e  COL    15   /* N
2e40: 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 73  OT USED. Databas
2e50: 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20  e lock protocol 
2e60: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
2e70: 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20   SQLITE_EMPTY   
2e80: 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61      16   /* Data
2e90: 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f  base is empty */
2ea0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2eb0: 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20  SCHEMA      17  
2ec0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
2ed0: 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20   schema changed 
2ee0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2ef0: 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38  E_TOOBIG      18
2f00: 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20     /* String or 
2f10: 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a  BLOB exceeds siz
2f20: 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69  e limit */.#defi
2f30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
2f40: 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62  AINT  19   /* Ab
2f50: 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 74 72  ort due to contr
2f60: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
2f70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2f80: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
2f90: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
2fa0: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
2fb0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
2fc0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
2fd0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
2fe0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
2ff0: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
3000: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
3010: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
3020: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
3030: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
3040: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
3050: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
3060: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
3070: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3080: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
3090: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
30a0: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
30b0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
30c0: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
30d0: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
30e0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
30f0: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
3100: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
3110: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
3120: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
3130: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
3140: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
3150: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
3160: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
3170: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
3180: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
3190: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
31a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
31b0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
31c0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
31d0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
31e0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
31f0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
3200: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
3210: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
3220: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
3230: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
3240: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
3250: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
3260: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
3270: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a   of 26 integer.*
3280: 2a 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 64  * result codes d
3290: 65 73 63 72 69 62 65 64 20 61 74 20 72 65 73 75  escribed at resu
32a0: 6c 74 2d 63 6f 64 65 73 2e 20 20 48 6f 77 65 76  lt-codes.  Howev
32b0: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
32c0: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a 2a  as shown that.**
32d0: 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72   many of these r
32e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
32f0: 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61 69 6e  too course-grain
3300: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
3310: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
3320: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
3330: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
3340: 73 20 75 73 65 72 73 20 6d 69 67 68 74 20 6c 69  s users might li
3350: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
3360: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
3370: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
3380: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
3390: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
33a0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
33b0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
33c0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
33d0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
33e0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
33f0: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
3400: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
3410: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
3420: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65  sult codes are e
3430: 6e 61 62 6c 65 64 20 28 6f 72 20 64 69 73 61 62  nabled (or disab
3440: 6c 65 64 29 20 66 6f 72 20 0a 2a 2a 20 65 61 63  led) for .** eac
3450: 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  h database.** co
3460: 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74  nnection using t
3470: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  he [sqlite3_exte
3480: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
3490: 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a  s()] API..** .**
34a0: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
34b0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
34c0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
34d0: 20 6c 69 73 74 65 64 20 61 62 6f 76 65 2e 0a 2a   listed above..*
34e0: 2a 20 57 65 20 65 78 70 65 63 74 20 74 68 65 20  * We expect the 
34f0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
3500: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3510: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
3520: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
3530: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
3540: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
3550: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
3560: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
3570: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
3580: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
3590: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
35a0: 20 0a 2a 2a 20 54 68 65 20 73 79 6d 62 6f 6c 69   .** The symboli
35b0: 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78  c name for an ex
35c0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
35d0: 64 65 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69  de always contai
35e0: 6e 73 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  ns a related.** 
35f0: 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  primary result c
3600: 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78 2e  ode as a prefix.
3610: 20 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74    Primary result
3620: 20 63 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20 61   codes contain a
3630: 20 73 69 6e 67 6c 65 0a 2a 2a 20 22 5f 22 20 63   single.** "_" c
3640: 68 61 72 61 63 74 65 72 2e 20 20 45 78 74 65 6e  haracter.  Exten
3650: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
3660: 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20   contain two or 
3670: 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63 74  more "_" charact
3680: 65 72 73 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d 65  ers..** The nume
3690: 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  ric value of an 
36a0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
36b0: 63 6f 64 65 20 63 61 6e 20 62 65 20 63 6f 6e 76  code can be conv
36c0: 65 72 74 65 64 20 74 6f 20 69 74 73 0a 2a 2a 20  erted to its.** 
36d0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72  corresponding pr
36e0: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
36f0: 65 20 62 79 20 6d 61 73 6b 69 6e 67 20 6f 66 66  e by masking off
3700: 20 74 68 65 20 6c 6f 77 65 72 20 38 20 62 79 74   the lower 8 byt
3710: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  es..**.** The SQ
3720: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63  LITE_OK result c
3730: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  ode will never b
3740: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20  e extended.  It 
3750: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62  will always.** b
3760: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a  e exactly zero..
3770: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3780: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20  E_IOERR_READ    
3790: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
37a0: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
37b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
37c0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
37d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
37e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
37f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
3800: 49 54 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  ITE         (SQL
3810: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
3820: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3830: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
3840: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3850: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OERR | (4<<8)).#
3860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3870: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20  ERR_DIR_FSYNC   
3880: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3890: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
38a0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
38b0: 52 55 4e 43 41 54 45 20 20 20 20 20 20 28 53 51  RUNCATE      (SQ
38c0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
38d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
38e0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
38f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
3900: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
3910: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3920: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
3930: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
3940: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
3950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
3960: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53  RDLOCK        (S
3970: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
3980: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
3990: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
39a0: 45 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  E        (SQLITE
39b0: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
39c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
39d0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
39e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
39f0: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 0a 2f  RR | (11<<8))../
3a00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
3a10: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
3a20: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
3a30: 0a 2a 2a 20 43 6f 6d 62 69 6e 61 74 69 6f 6e 20  .** Combination 
3a40: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
3a50: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
3a60: 75 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 74  used as the.** t
3a70: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
3a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
3a90: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
3aa0: 63 65 20 61 6e 64 0a 2a 2a 20 61 73 20 66 6f 75  ce and.** as fou
3ab0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
3ac0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
3ad0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
3ae0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
3af0: 0a 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  .**.*/.#define S
3b00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
3b10: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
3b20: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
3b30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
3b40: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
3b50: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
3b60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
3b70: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
3b80: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
3b90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
3ba0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
3bb0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
3bc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
3bd0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
3be0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
3bf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
3c00: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
3c10: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
3c20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
3c30: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
3c40: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
3c50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
3c60: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
3c70: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
3c80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
3c90: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
3ca0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
3cb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
3cc0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
3cd0: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
3ce0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
3cf0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
3d00: 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53  002000.#define S
3d10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
3d20: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
3d30: 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  004000../*.** CA
3d40: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
3d50: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
3d60: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
3d70: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
3d80: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
3d90: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
3da0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
3db0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
3dc0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
3dd0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a  f the following.
3de0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
3df0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
3e00: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
3e10: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
3e20: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
3e30: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
3e40: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
3e50: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
3e60: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
3e70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
3e80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
3e90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
3ea0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
3eb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
3ec0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
3ed0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
3ee0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
3ef0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
3f00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
3f10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
3f20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
3f30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
3f40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
3f50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
3f60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
3f70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
3f80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
3f90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
3fa0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
3fb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
3fc0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
3fd0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
3fe0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
3ff0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
4000: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
4010: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
4020: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
4030: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4040: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
4050: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
4060: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
4070: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
4080: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
4090: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
40a0: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
40b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
40c0: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
40d0: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
40e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
40f0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
4100: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
4110: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4120: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
4130: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
4140: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4150: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
4160: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
4170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4180: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
4190: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
41a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
41b0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
41c0: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
41d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
41e0: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
41f0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
4200: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4210: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
4220: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
4230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4240: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
4250: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
4260: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4270: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
4280: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
4290: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
42a0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
42b0: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
42c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
42d0: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
42e0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
42f0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
4300: 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 76  lowing integer v
4310: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
4320: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
4330: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
4340: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
4350: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
4360: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
4370: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
4380: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
4390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
43a0: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
43b0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
43c0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
43d0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
43e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
43f0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
4400: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
4410: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
4420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4430: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
4440: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
4450: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
4460: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a  tion Type Flags.
4470: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
4480: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
4490: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
44a0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
44b0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
44c0: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
44d0: 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66  ination of the f
44e0: 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
44f0: 20 76 61 6c 75 65 73 20 61 73 0a 2a 2a 20 74 68   values as.** th
4500: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
4510: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
4520: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
4530: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
4540: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
4550: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
4560: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
4570: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
4580: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
4590: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
45a0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
45b0: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 20 54  t be flushed.  T
45c0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
45d0: 4f 52 4d 41 4c 20 6d 65 61 6e 73 20 0a 2a 2a 20  ORMAL means .** 
45e0: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
45f0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
4600: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e    The SQLITE_SYN
4610: 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e  C_FULL flag mean
4620: 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  s .** to use Mac
4630: 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS-X style full
4640: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
4650: 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66  fsync()..*/.#def
4660: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
4670: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
4680: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
4690: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
46a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
46c0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
46d0: 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a 2a    0x00010.../*.*
46e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
46f0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
4700: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
4710: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
4720: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
4730: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
4740: 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e   in the OS.** in
4750: 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20  terface layer.  
4760: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
4770: 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e  terface implemen
4780: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
4790: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
47a0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
47b0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
47c0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
47d0: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
47e0: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
47f0: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
4800: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
4810: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
4820: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
4830: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
4840: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
4850: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
4860: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
4870: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
4880: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
4890: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
48a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
48b0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
48c0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
48d0: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
48e0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
48f0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
4900: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
4910: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
4920: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
4930: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
4940: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
4950: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
4960: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
4970: 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73 20  method contains 
4980: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
4990: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
49a0: 68 65 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20  he this object. 
49b0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
49c0: 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74 68  ines the.** meth
49d0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
49e0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
49f0: 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20 74  ations against t
4a00: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a  he open file..**
4a10: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
4a20: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
4a30: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
4a40: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
4a50: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
4a60: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
4a70: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
4a80: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
4a90: 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65 63  nc()..*  The sec
4aa0: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 6e  ond choice is an
4ab0: 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20 66  .** OS-X style f
4ac0: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53 51  ullsync.  The SQ
4ad0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66  LITE_SYNC_DATA f
4ae0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
4af0: 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61 74  in to.** indicat
4b00: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
4b10: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
4b20: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
4b30: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a 2a  de needs to be.*
4b40: 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a 2a  * synced..** .**
4b50: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
4b60: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
4b70: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
4b80: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
4b90: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
4ba0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
4bb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
4bc0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
4bd0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
4be0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
4bf0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
4c00: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
4c10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
4c20: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
4c30: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
4c40: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
4c50: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
4c60: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
4c70: 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68 65  k.  .** The xChe
4c80: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
4c90: 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a   method looks.**
4ca0: 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20 64   to see if any d
4cb0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4cc0: 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74 68  on, either in th
4cd0: 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72  is.** process or
4ce0: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
4cf0: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
4d00: 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c 0a  ng an RESERVED,.
4d10: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
4d20: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
4d30: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
4d40: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
4d50: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
4d60: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 69  ists and false i
4d70: 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  f not..** .** Th
4d80: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
4d90: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
4da0: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
4db0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
4dc0: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
4dd0: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
4de0: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
4df0: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
4e00: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4e10: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
4e20: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
4e30: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
4e40: 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e  ment.** is an in
4e50: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 20  teger opcode.   
4e60: 54 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  The third.** arg
4e70: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
4e80: 69 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ic pointer which
4e90: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
4ea0: 62 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  be a pointer.** 
4eb0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
4ec0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
4ed0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
4ee0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
4ef0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
4f00: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
4f10: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
4f20: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
4f30: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
4f40: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
4f50: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
4f60: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
4f70: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
4f80: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
4f90: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
4fa0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
4fb0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
4fc0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
4fd0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
4fe0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
4ff0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
5000: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 6f   core reserves o
5010: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
5020: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
5030: 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51 4c   use. .** A [SQL
5040: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
5050: 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  ATE | list of op
5060: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
5070: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
5080: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
5090: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
50a0: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
50b0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
50c0: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20 0a  ld use opcodes .
50d0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
50e0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
50f0: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  flicts..**.** Th
5100: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
5110: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
5120: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
5130: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
5140: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
5150: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
5160: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
5170: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
5180: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
5190: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
51a0: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
51b0: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
51c0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
51d0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
51e0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
51f0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
5200: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
5210: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
5220: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
5230: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
5240: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5250: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
5260: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
5270: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
5280: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5290: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
52a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
52b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
52c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
52d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
52e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
52f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
5300: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5310: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
5320: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5330: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
5340: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5350: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
5360: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5370: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
5380: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
5390: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
53a0: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
53b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
53c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
53d0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
53e0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
53f0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
5400: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5420: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
5430: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
5440: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
5450: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
5460: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
5470: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
5480: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
5490: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
54a0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
54b0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
54c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
54d0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
54e0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
54f0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
5500: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
5510: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
5520: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
5530: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
5540: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
5550: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
5560: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
5570: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5580: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
5590: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
55a0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
55b0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
55c0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
55d0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
55e0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
55f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
5600: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5610: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
5620: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
5630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5640: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
5650: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
5660: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
5670: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
5680: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
5690: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
56a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
56b0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
56c0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
56d0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
56e0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
56f0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
5700: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
5710: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
5720: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
5730: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
5740: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
5750: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
5760: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
5770: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
5780: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
5790: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
57a0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
57b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
57c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
57d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
57e0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
57f0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
5800: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
5810: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  *);.  int (*xFil
5820: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
5830: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
5840: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
5850: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
5860: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
5870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
5880: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
5890: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
58a0: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
58b0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
58c0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
58d0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
58e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
58f0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
5900: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
5910: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
5920: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
5930: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
5940: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
5950: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
5960: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5970: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
5980: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5990: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
59a0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
59b0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
59c0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
59d0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
59e0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
59f0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
5a00: 61 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  ases the xFileCo
5a10: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
5a20: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
5a30: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
5a40: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
5a50: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5a60: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
5a70: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
5a80: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
5a90: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
5aa0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
5ab0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
5ac0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
5ad0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
5ae0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
5af0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 20 54 68 69   points to.  Thi
5b00: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
5b10: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
5b20: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
5b30: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
5b40: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
5b50: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
5b60: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
5b70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
5b80: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
5b90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5ba0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
5bb0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
5bc0: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
5bd0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
5be0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
5bf0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
5c00: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
5c10: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
5c20: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
5c30: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
5c40: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
5c50: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
5c60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
5c70: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
5c80: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
5c90: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5ca0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
5cb0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
5cc0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
5cd0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
5ce0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
5cf0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
5d00: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
5d10: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
5d20: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
5d30: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
5d40: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
5d50: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
5d60: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
5d70: 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a  ce between the.*
5d80: 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  * SQLite core an
5d90: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
5da0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
5db0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
5dc0: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
5dd0: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
5de0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
5df0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
5e00: 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20  ** The iVersion 
5e10: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
5e20: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
5e30: 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74 75 72  larger for futur
5e40: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
5e50: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
5e60: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
5e70: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
5e80: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
5e90: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
5ea0: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
5eb0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
5ec0: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
5ed0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
5ee0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
5ef0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
5f00: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
5f10: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
5f20: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
5f30: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
5f40: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
5f50: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
5f60: 65 67 69 73 74 65 72 65 64 20 76 66 73 20 6d 6f  egistered vfs mo
5f70: 64 75 6c 65 73 20 61 72 65 20 6b 65 70 74 20 6f  dules are kept o
5f80: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
5f90: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
5fa0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
5fb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
5fc0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
5fd0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
5fe0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
5ff0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
6000: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
6010: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
6020: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
6030: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
6040: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
6050: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 0a 2a  ches the list..*
6060: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
6070: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
6080: 20 66 69 65 6c 64 73 20 69 6e 20 74 68 65 20 73   fields in the s
6090: 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20 73  qlite3_vfs .** s
60a0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
60b0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
60c0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
60d0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
60e0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
60f0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
6100: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
6110: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
6120: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
6130: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
6140: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
6150: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
6160: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
6170: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
6180: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
6190: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
61a0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
61b0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
61c0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
61d0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
61e0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
61f0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
6200: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  s..**.** SQLite 
6210: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
6220: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
6230: 65 20 73 74 72 69 6e 67 20 70 61 73 73 65 64 20  e string passed 
6240: 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20 69 73  to.** xOpen() is
6250: 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61 6d 65   a full pathname
6260: 20 61 73 20 67 65 6e 65 72 61 74 65 64 20 62 79   as generated by
6270: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
6280: 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74 68 65   and.** that the
6290: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
62a0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
62b0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
62c0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
62d0: 20 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65    So the [sqlite
62e0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72  3_file] can stor
62f0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
6300: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
6310: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
6320: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
6330: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
6340: 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  son..**.** The f
6350: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6360: 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20 63 6f   xOpen() is a co
6370: 70 79 20 6f 66 20 74 68 65 20 66 6c 61 67 73 20  py of the flags 
6380: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
6390: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
63a0: 29 5d 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33  )].  If [sqlite3
63b0: 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c  _open()] or [sql
63c0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 0a 2a  ite3_open16()].*
63d0: 2a 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  * is used, then 
63e0: 66 6c 61 67 73 20 69 73 20 5b 53 51 4c 49 54 45  flags is [SQLITE
63f0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
6400: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
6410: 43 52 45 41 54 45 5d 2e 0a 2a 2a 20 49 66 20 78  CREATE]..** If x
6420: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
6430: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
6440: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
6450: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
6460: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
6470: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
6480: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
6490: 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20  Flags may be.** 
64a0: 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69  set..** .** SQLi
64b0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
64c0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
64d0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
64e0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
64f0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
6500: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
6510: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a 2a 2a  g opened:.** .**
6520: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
6530: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
6540: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
6550: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6560: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
6570: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
6580: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
6590: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
65a0: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
65b0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
65c0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
65d0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
65e0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
65f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
6600: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
6610: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  OURNAL].** </ul>
6620: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
6630: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
6640: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
6650: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
6660: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74   to.** changes t
6670: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
6680: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
6690: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
66a0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
66b0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
66c0: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
66d0: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 2c  ery or rollback,
66e0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
66f0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
6700: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
6710: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
6720: 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72 65 0a 2a  is journal are.*
6730: 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e 20  * also a no-op. 
6740: 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
6750: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
6760: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 49   return SQLITE_I
6770: 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 68 65 20  OERR..** Or the 
6780: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
6790: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
67a0: 68 65 20 61 20 64 61 74 61 62 61 73 65 20 66 69  he a database fi
67b0: 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 64 6f  le will.** be do
67c0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
67d0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
67e0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
67f0: 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20 61 6e  ndom order.** an
6800: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
6810: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
6820: 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53  dingly..** .** S
6830: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
6840: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
6850: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
6860: 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
6870: 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  method:.** .** <
6880: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
6890: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
68a0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
68b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
68c0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
68d0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  .** .** The [SQL
68e0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
68f0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
6900: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
6910: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
6920: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
6930: 65 64 2e 20 20 54 68 69 73 20 77 69 6c 6c 20 61  ed.  This will a
6940: 6c 77 61 79 73 20 62 65 20 73 65 74 20 66 6f 72  lways be set for
6950: 20 54 45 4d 50 20 0a 2a 2a 20 64 61 74 61 62 61   TEMP .** databa
6960: 73 65 73 20 61 6e 64 20 6a 6f 75 72 6e 61 6c 73  ses and journals
6970: 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72   and for subjour
6980: 6e 61 6c 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b  nals.  The .** [
6990: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
69a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e  USIVE] flag mean
69b0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
69c0: 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66  d be opened.** f
69d0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
69e0: 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20  ess.  This flag 
69f0: 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66  is set for all f
6a00: 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66  iles except.** f
6a10: 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
6a20: 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 0a 2a  base file..** .*
6a30: 2a 20 53 70 61 63 65 20 74 6f 20 68 6f 6c 64 20  * Space to hold 
6a40: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
6a50: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
6a60: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
6a70: 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  d .** argument t
6a80: 6f 20 78 4f 70 65 6e 20 69 73 20 61 6c 6c 6f 63  o xOpen is alloc
6a90: 61 74 65 64 20 62 79 20 63 61 6c 6c 65 72 20 28  ated by caller (
6aa0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 29  the SQLite core)
6ab0: 2e 20 0a 2a 2a 20 73 7a 4f 73 46 69 6c 65 20 62  . .** szOsFile b
6ac0: 79 74 65 73 20 61 72 65 20 61 6c 6c 6f 63 61 74  ytes are allocat
6ad0: 65 64 20 66 6f 72 20 74 68 69 73 20 6f 62 6a 65  ed for this obje
6ae0: 63 74 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  ct.  The xOpen m
6af0: 65 74 68 6f 64 0a 2a 2a 20 66 69 6c 6c 73 20 69  ethod.** fills i
6b00: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
6b10: 73 70 61 63 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  space..** .** Th
6b20: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
6b30: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
6b40: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
6b50: 45 53 53 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20  ESS_EXISTS] .** 
6b60: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
6b70: 65 78 69 73 74 61 6e 63 65 20 6f 66 20 61 20 66  existance of a f
6b80: 69 6c 65 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  ile,.** or [SQLI
6b90: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
6ba0: 49 54 45 5d 20 74 6f 20 74 65 73 74 20 74 6f 20  ITE] to test to 
6bb0: 73 65 65 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65  see.** if a file
6bc0: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
6bd0: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
6be0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
6bf0: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f  D].** to test to
6c00: 20 73 65 65 20 69 66 20 61 20 66 69 6c 65 20 69   see if a file i
6c10: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
6c20: 62 6c 65 2e 20 20 54 68 65 20 66 69 6c 65 20 63  ble.  The file c
6c30: 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69 72 65  an be a .** dire
6c40: 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51  ctory..** .** SQ
6c50: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
6c60: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
6c70: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
6c80: 62 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  byte for.** the 
6c90: 6f 75 74 70 75 74 20 62 75 66 66 65 72 73 20 66  output buffers f
6ca0: 6f 72 20 78 47 65 74 54 65 6d 70 6e 61 6d 65 20  or xGetTempname 
6cb0: 61 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  and xFullPathnam
6cc0: 65 2e 20 54 68 65 20 65 78 61 63 74 0a 2a 2a 20  e. The exact.** 
6cd0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
6ce0: 75 74 20 62 75 66 66 65 72 20 69 73 20 61 6c 73  ut buffer is als
6cf0: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
6d00: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
6d10: 0a 2a 2a 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  .** methods. If 
6d20: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
6d30: 72 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  r is not large e
6d40: 6e 6f 75 67 68 2c 20 53 51 4c 49 54 45 5f 43 41  nough, SQLITE_CA
6d50: 4e 54 4f 50 45 4e 0a 2a 2a 20 73 68 6f 75 6c 64  NTOPEN.** should
6d60: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 41 73   be returned. As
6d70: 20 74 68 69 73 20 69 73 20 68 61 6e 64 6c 65 64   this is handled
6d80: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
6d90: 72 20 62 79 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  r by SQLite,.** 
6da0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
6db0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 76  ons should endev
6dc0: 6f 75 72 20 74 6f 20 70 72 65 76 65 6e 74 20 74  our to prevent t
6dd0: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 0a  his by setting .
6de0: 2a 2a 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ** mxPathname to
6df0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
6e00: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 20  large value..** 
6e10: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
6e20: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
6e30: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
6e40: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
6e50: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  * are not strict
6e60: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
6e70: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
6e80: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
6e90: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
6ea0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
6eb0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
6ec0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
6ed0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
6ee0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
6ef0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
6f00: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
6f10: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
6f20: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
6f30: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
6f40: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
6f50: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
6f60: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 20 20  ness obtained.  
6f70: 54 68 65 0a 2a 2a 20 78 53 6c 65 65 70 28 29 20  The.** xSleep() 
6f80: 6d 65 74 68 6f 64 20 63 61 75 73 65 20 74 68 65  method cause the
6f90: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
6fa0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
6fb0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
6fc0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
6fd0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20  nds given.  The 
6fe0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
6ff0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7000: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
7010: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
7020: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a 2a  rent date and.**
7030: 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   time..*/.typede
7040: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7050: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
7060: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7070: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
7080: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
7090: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
70a0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f  ersion number */
70b0: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
70c0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
70d0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
70e0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
70f0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
7100: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
7110: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
7120: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
7130: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
7140: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
7150: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
7160: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
7170: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
7180: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
7190: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
71a0: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
71b0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
71c0: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
71d0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
71e0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
71f0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
7200: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7210: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
7220: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
7230: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
7240: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
7250: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
7260: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
7270: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
7280: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
7290: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
72a0: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
72b0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
72c0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
72d0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  gs);.  int (*xGe
72e0: 74 54 65 6d 70 6e 61 6d 65 29 28 73 71 6c 69 74  tTempname)(sqlit
72f0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 4f 75  e3_vfs*, int nOu
7300: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
7310: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
7320: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
7330: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
7340: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
7350: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
7360: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
7370: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
7380: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
7390: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
73a0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
73b0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
73c0: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
73d0: 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  g);.  void *(*xD
73e0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
73f0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
7400: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a  char *zSymbol);.
7410: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
7420: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
7430: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
7440: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
7450: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
7460: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
7470: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
7480: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
7490: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
74a0: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
74b0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
74c0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
74d0: 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c  );.  /* New fiel
74e0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
74f0: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
7500: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
7510: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
7520: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
7530: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
7540: 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  pens. */.};../*.
7550: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
7560: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
7570: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
7580: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7590: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
75a0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
75b0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
75c0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
75d0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
75e0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
75f0: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
7600: 69 6e 65 0a 2a 2a 20 74 68 65 20 6b 69 6e 64 20  ine.** the kind 
7610: 6f 66 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  of what kind of 
7620: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
7630: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
7640: 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  s.** looking for
7650: 2e 20 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  .  With SQLITE_A
7660: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
7670: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
7680: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
7690: 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  s to see if the 
76a0: 66 69 6c 65 20 65 78 69 73 74 73 2e 20 20 57 69  file exists.  Wi
76b0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
76c0: 5f 52 45 41 44 57 52 49 54 45 2c 0a 2a 2a 20 74  _READWRITE,.** t
76d0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
76e0: 64 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20  d checks to see 
76f0: 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 62  if the file is b
7700: 6f 74 68 20 72 65 61 64 61 62 6c 65 0a 2a 2a 20  oth readable.** 
7710: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 20 20 57  and writable.  W
7720: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
7730: 53 5f 52 45 41 44 20 74 68 65 20 78 41 63 63 65  S_READ the xAcce
7740: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
7750: 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68  cks to see if th
7760: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
7770: 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  le..*/.#define S
7780: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
7790: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
77a0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
77b0: 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69  EADWRITE 1.#defi
77c0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
77d0: 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a  _READ      2../*
77e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
77f0: 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
7800: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
7810: 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  Codes.**.** This
7820: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
7830: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
7840: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
7850: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
7860: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
7870: 66 65 61 74 75 72 65 2e 0a 2a 2a 20 42 79 20 64  feature..** By d
7880: 65 66 61 75 6c 74 2c 20 53 51 4c 69 74 65 20 41  efault, SQLite A
7890: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
78a0: 72 6e 20 6f 6e 65 20 6f 66 20 6f 6e 6c 79 20 32  rn one of only 2
78b0: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
78c0: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
78d0: 20 63 6f 64 65 73 5d 2e 20 20 57 68 65 6e 20 65   codes].  When e
78e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
78f0: 6f 64 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  odes.** are enab
7900: 6c 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  led by this rout
7910: 69 6e 65 2c 20 74 68 65 20 72 65 70 65 74 6f 69  ine, the repetoi
7920: 72 65 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 64  re of result cod
7930: 65 73 20 63 61 6e 20 62 65 0a 2a 2a 20 6d 75 63  es can be.** muc
7940: 68 20 6c 61 72 67 65 72 20 61 6e 64 20 63 61 6e  h larger and can
7950: 20 28 68 6f 70 65 66 75 6c 6c 79 29 20 70 72 6f   (hopefully) pro
7960: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
7970: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
7980: 2a 20 61 62 6f 75 74 20 74 68 65 20 63 61 75 73  * about the caus
7990: 65 20 6f 66 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  e of an error..*
79a0: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
79b0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 62 6f  argument is a bo
79c0: 6f 6c 65 61 6e 20 76 61 6c 75 65 20 74 68 61 74  olean value that
79d0: 20 74 75 72 6e 73 20 65 78 74 65 6e 64 65 64 20   turns extended 
79e0: 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
79f0: 6f 6e 20 61 6e 64 20 6f 66 66 2e 20 20 45 78 74  on and off.  Ext
7a00: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
7a10: 65 73 20 61 72 65 20 6f 66 66 20 62 79 20 64 65  es are off by de
7a20: 66 61 75 6c 74 20 66 6f 72 0a 2a 2a 20 62 61 63  fault for.** bac
7a30: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
7a40: 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
7a50: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
7a60: 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
7a70: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
7a80: 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
7a90: 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
7aa0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7ab0: 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
7ac0: 64 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  d.**.** Each ent
7ad0: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
7ae0: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
7af0: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
7b00: 20 69 6e 74 65 67 65 72 20 6b 65 79 0a 2a 2a 20   integer key.** 
7b10: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
7b20: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
7b30: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
7b40: 65 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  e as an undeclar
7b50: 65 64 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 61 6d  ed.** column nam
7b60: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
7b70: 72 20 5f 52 4f 57 49 44 5f 2e 20 20 49 66 20 74  r _ROWID_.  If t
7b80: 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
7b90: 6f 6c 75 6d 6e 20 6f 66 0a 2a 2a 20 74 79 70 65  olumn of.** type
7ba0: 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
7bb0: 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20 63   KEY then that c
7bc0: 6f 6c 75 6d 6e 20 69 73 20 61 6e 6f 74 68 65 72  olumn is another
7bd0: 20 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68   an alias for th
7be0: 65 0a 2a 2a 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a  e.** rowid..**.*
7bf0: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
7c00: 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64  eturns the rowid
7c10: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
7c20: 65 6e 74 20 49 4e 53 45 52 54 20 69 6e 74 6f 0a  ent INSERT into.
7c30: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
7c40: 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73  from the databas
7c50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 67 69 76  e connection giv
7c60: 65 6e 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  en in the first 
7c70: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  .** argument.  I
7c80: 66 20 6e 6f 20 69 6e 73 65 72 74 73 20 68 61 76  f no inserts hav
7c90: 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
7ca0: 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61 73 65  on this database
7cb0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  .** connection, 
7cc0: 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
7cd0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e  ..**.** If an IN
7ce0: 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68  SERT occurs with
7cf0: 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68  in a trigger, th
7d00: 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  en the rowid of 
7d10: 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20  the.** inserted 
7d20: 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
7d30: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
7d40: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
7d50: 72 69 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e  rigger.** is run
7d60: 6e 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20  ning.  But once 
7d70: 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d  the trigger term
7d80: 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75  inates, the valu
7d90: 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
7da0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
7db0: 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73  verts to the las
7dc0: 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64  t value inserted
7dd0: 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74   before the.** t
7de0: 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a  rigger fired..**
7df0: 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
7e00: 68 72 65 61 64 20 64 6f 65 73 20 61 20 6e 65 77  hread does a new
7e10: 20 69 6e 73 65 72 74 20 6f 6e 20 74 68 65 20 73   insert on the s
7e20: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
7e30: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
7e40: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
7e50: 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
7e60: 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
7e70: 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c  st insert rowid,
7e80: 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
7e90: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
7ea0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
7eb0: 65 66 69 6e 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74  efined..*/.sqlit
7ec0: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
7ed0: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
7ee0: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
7ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
7f00: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
7f10: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
7f20: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
7f30: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
7f40: 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
7f50: 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
7f60: 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 28 6f  re changed.** (o
7f70: 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
7f80: 6c 65 74 65 64 29 20 62 79 20 74 68 65 20 6d 6f  leted) by the mo
7f90: 73 74 20 72 65 63 65 6e 74 20 53 51 4c 20 73 74  st recent SQL st
7fa0: 61 74 65 6d 65 6e 74 2e 20 20 4f 6e 6c 79 0a 2a  atement.  Only.*
7fb0: 2a 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  * changes that a
7fc0: 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
7fd0: 69 66 69 65 64 20 62 79 20 74 68 65 20 49 4e 53  ified by the INS
7fe0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a  ERT, UPDATE, or.
7ff0: 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
8000: 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
8010: 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
8020: 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
8030: 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f   triggers are no
8040: 74 20 63 6f 75 6e 74 65 64 2e 20 20 55 73 65 20  t counted.  Use 
8050: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
8060: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
8070: 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e  nction.** to fin
8080: 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
8090: 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
80a0: 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
80b0: 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
80c0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 57 69 74 68 69 6e  rs..**.** Within
80d0: 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74   the body of a t
80e0: 72 69 67 67 65 72 2c 20 74 68 65 20 73 71 6c 69  rigger, the sqli
80f0: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
8100: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 0a 2a  terface can be.*
8110: 2a 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64  * called to find
8120: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
8130: 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  * changes in the
8140: 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
8150: 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
8160: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
8170: 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
8180: 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  within the body 
8190: 6f 66 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a  of the trigger..
81a0: 2a 2a 0a 2a 2a 20 41 6c 6c 20 63 68 61 6e 67 65  **.** All change
81b0: 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2c 20 65  s are counted, e
81c0: 76 65 6e 20 69 66 20 74 68 65 79 20 77 65 72 65  ven if they were
81d0: 20 6c 61 74 65 72 20 75 6e 64 6f 6e 65 20 62 79   later undone by
81e0: 20 61 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b 20 6f   a.** ROLLBACK o
81f0: 72 20 41 42 4f 52 54 2e 20 20 45 78 63 65 70 74  r ABORT.  Except
8200: 2c 20 63 68 61 6e 67 65 73 20 61 73 73 6f 63 69  , changes associ
8210: 61 74 65 64 20 77 69 74 68 20 63 72 65 61 74 69  ated with creati
8220: 6e 67 20 61 6e 64 0a 2a 2a 20 64 72 6f 70 70 69  ng and.** droppi
8230: 6e 67 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  ng tables are no
8240: 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  t counted..**.**
8250: 20 49 66 20 61 20 63 61 6c 6c 62 61 63 6b 20 69   If a callback i
8260: 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
8270: 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
8280: 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
8290: 72 73 69 76 65 6c 79 2c 0a 2a 2a 20 74 68 65 6e  rsively,.** then
82a0: 20 74 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20   the changes in 
82b0: 74 68 65 20 69 6e 6e 65 72 2c 20 72 65 63 75 72  the inner, recur
82c0: 73 69 76 65 20 63 61 6c 6c 20 61 72 65 20 63 6f  sive call are co
82d0: 75 6e 74 65 64 20 74 6f 67 65 74 68 65 72 0a 2a  unted together.*
82e0: 2a 20 77 69 74 68 20 74 68 65 20 63 68 61 6e 67  * with the chang
82f0: 65 73 20 69 6e 20 74 68 65 20 6f 75 74 65 72 20  es in the outer 
8300: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  call..**.** SQLi
8310: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
8320: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
8330: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
8340: 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c  thout a WHERE cl
8350: 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70  ause.** by dropp
8360: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
8370: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
8380: 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73  This is much fas
8390: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a  ter than going.*
83a0: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65  * through and de
83b0: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61  leting individua
83c0: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20  l elements from 
83d0: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63  the table.)  Bec
83e0: 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20  ause of.** this 
83f0: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
8400: 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66  e change count f
8410: 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  or "DELETE FROM 
8420: 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a  table" will be.*
8430: 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73  * zero regardles
8440: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  s of the number 
8450: 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74  of elements that
8460: 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79   were originally
8470: 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65   in the.** table
8480: 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75  . To get an accu
8490: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68  rate count of th
84a0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
84b0: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a   deleted, use.**
84c0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
84d0: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73  ble WHERE 1" ins
84e0: 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tead..**.** If a
84f0: 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d 61  nother thread ma
8500: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
8510: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
8520: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
8530: 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
8540: 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  e is running the
8550: 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
8560: 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ue of this routi
8570: 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ne.** is undefin
8580: 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
8590: 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
85a0: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
85b0: 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
85c0: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
85d0: 66 69 65 64 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73  fied.***.** This
85e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
85f0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
8600: 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
8610: 61 74 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20  at have been.** 
8620: 6d 6f 64 69 66 69 65 64 20 62 79 20 49 4e 53 45  modified by INSE
8630: 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
8640: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
8650: 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
8660: 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73  se handle.** was
8670: 20 6f 70 65 6e 65 64 2e 20 54 68 69 73 20 69 6e   opened. This in
8680: 63 6c 75 64 65 73 20 55 50 44 41 54 45 2c 20 49  cludes UPDATE, I
8690: 4e 53 45 52 54 20 61 6e 64 20 44 45 4c 45 54 45  NSERT and DELETE
86a0: 20 73 74 61 74 65 6d 65 6e 74 73 20 65 78 65 63   statements exec
86b0: 75 74 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  uted.** as part 
86c0: 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
86d0: 61 6d 73 2e 20 41 6c 6c 20 63 68 61 6e 67 65 73  ams. All changes
86e0: 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20   are counted as 
86f0: 73 6f 6f 6e 20 61 73 20 74 68 65 0a 2a 2a 20 73  soon as the.** s
8700: 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
8710: 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70  kes them is comp
8720: 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
8730: 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
8740: 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f   is.** passed to
8750: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
8760: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
8770: 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
8780: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
8790: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 28  [sqlite3_change(
87a0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
87b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
87c0: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
87d0: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
87e0: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20  able" without a 
87f0: 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20  WHERE clause.** 
8800: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
8810: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
8820: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
8830: 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e  much faster than
8840: 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67   going.** throug
8850: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
8860: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
8870: 74 73 20 66 6f 72 6d 20 74 68 65 20 74 61 62 6c  ts form the tabl
8880: 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a  e.)  Because of.
8890: 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61  ** this optimiza
88a0: 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65  tion, the change
88b0: 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45   count for "DELE
88c0: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
88d0: 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72  ill be.** zero r
88e0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
88f0: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
8900: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
8910: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a  iginally in the.
8920: 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74  ** table. To get
8930: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
8940: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
8950: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
8960: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
8970: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
8980: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a  E 1" instead..**
8990: 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
89a0: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
89b0: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
89c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
89d0: 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69  ion.** while thi
89e0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
89f0: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 72 65  ning then the re
8a00: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
8a10: 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73  is routine.** is
8a20: 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69   undefined..*/.i
8a30: 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
8a40: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
8a50: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
8a60: 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
8a70: 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
8a80: 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ery.**.** This f
8a90: 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
8aa0: 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
8ab0: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
8ac0: 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
8ad0: 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
8ae0: 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
8af0: 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
8b00: 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
8b10: 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
8b20: 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
8b30: 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
8b40: 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
8b50: 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
8b60: 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
8b70: 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
8b80: 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
8b90: 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
8ba0: 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20  *.** It is safe 
8bb0: 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
8bc0: 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
8bd0: 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
8be0: 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
8bf0: 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
8c00: 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
8c10: 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
8c20: 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
8c30: 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
8c40: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
8c50: 74 68 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  th a database co
8c60: 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a  nnection that.**
8c70: 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
8c80: 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
8c90: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
8ca0: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
8cb0: 0a 2a 2a 20 54 68 65 20 53 51 4c 20 6f 70 65 72  .** The SQL oper
8cc0: 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
8cd0: 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
8ce0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
8cf0: 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20  TERRUPT]..** If 
8d00: 61 6e 20 69 6e 74 65 72 72 75 70 74 65 64 20 6f  an interrupted o
8d10: 70 65 72 61 74 69 6f 6e 20 77 61 73 20 61 6e 20  peration was an 
8d20: 75 70 64 61 74 65 20 74 68 61 74 20 69 73 20 69  update that is i
8d30: 6e 73 69 64 65 20 61 6e 0a 2a 2a 20 65 78 70 6c  nside an.** expl
8d40: 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
8d50: 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
8d60: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69  e transaction wi
8d70: 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 0a 2a 2a 20  ll be rolled.** 
8d80: 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
8d90: 6c 79 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ly..*/.void sqli
8da0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
8db0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
8dc0: 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
8dd0: 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
8de0: 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
8df0: 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
8e00: 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
8e10: 20 74 72 75 65 20 69 66 20 74 68 65 20 67 69 76   true if the giv
8e20: 65 6e 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  en input string 
8e30: 63 6f 6d 70 72 69 73 65 73 0a 2a 2a 20 6f 6e 65  comprises.** one
8e40: 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 74   or more complet
8e50: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
8e60: 2e 20 46 6f 72 20 74 68 65 20 73 71 6c 69 74 65  . For the sqlite
8e70: 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 63 61 6c  3_complete() cal
8e80: 6c 2c 0a 2a 2a 20 74 68 65 20 70 61 72 61 6d 65  l,.** the parame
8e90: 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 6e 75  ter must be a nu
8ea0: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  l-terminated UTF
8eb0: 2d 38 20 73 74 72 69 6e 67 2e 20 46 6f 72 0a 2a  -8 string. For.*
8ec0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  * sqlite3_comple
8ed0: 74 65 31 36 28 29 2c 20 61 20 6e 75 6c 2d 74 65  te16(), a nul-te
8ee0: 72 6d 69 6e 61 74 65 64 20 6d 61 63 68 69 6e 65  rminated machine
8ef0: 20 62 79 74 65 20 6f 72 64 65 72 20 55 54 46 2d   byte order UTF-
8f00: 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 73 20  16 string.** is 
8f10: 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
8f20: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
8f30: 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
8f40: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
8f50: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
8f60: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
8f70: 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 66  y entered text f
8f80: 6f 72 6d 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  orms one or more
8f90: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
8fa0: 61 74 65 6d 65 6e 74 73 20 6f 72 0a 2a 2a 20 69  atements or.** i
8fb0: 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
8fc0: 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
8fd0: 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
8fe0: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 74 6f 0a  statements into.
8ff0: 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
9000: 72 73 69 6e 67 2e 20 54 68 65 20 61 6c 67 6f 72  rsing. The algor
9010: 69 74 68 6d 20 69 73 20 73 69 6d 70 6c 65 2e 20  ithm is simple. 
9020: 20 49 66 20 74 68 65 20 0a 2a 2a 20 6c 61 73 74   If the .** last
9030: 20 74 6f 6b 65 6e 20 6f 74 68 65 72 20 74 68 61   token other tha
9040: 6e 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6d  n spaces and com
9050: 6d 65 6e 74 73 20 69 73 20 61 20 73 65 6d 69 63  ments is a semic
9060: 6f 6c 6f 6e 2c 20 74 68 65 6e 20 72 65 74 75 72  olon, then retur
9070: 6e 20 0a 2a 2a 20 74 72 75 65 2e 20 20 41 63 74  n .** true.  Act
9080: 75 61 6c 6c 79 2c 20 74 68 65 20 61 6c 67 6f 72  ually, the algor
9090: 69 74 68 6d 20 69 73 20 61 20 6c 69 74 74 6c 65  ithm is a little
90a0: 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65   more complicate
90b0: 64 20 74 68 61 6e 20 74 68 61 74 0a 2a 2a 20 69  d than that.** i
90c0: 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 61 6c 20  n order to deal 
90d0: 77 69 74 68 20 74 72 69 67 67 65 72 73 2c 20 62  with triggers, b
90e0: 75 74 20 74 68 65 20 62 61 73 69 63 20 69 64 65  ut the basic ide
90f0: 61 20 69 73 20 74 68 65 20 73 61 6d 65 3a 20 20  a is the same:  
9100: 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
9110: 20 69 73 20 6e 6f 74 20 63 6f 6d 70 6c 65 74 65   is not complete
9120: 20 75 6e 6c 65 73 73 20 69 74 20 65 6e 64 73 20   unless it ends 
9130: 69 6e 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2e 0a  in a semicolon..
9140: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
9150: 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
9160: 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
9170: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
9180: 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
9190: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
91a0: 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
91b0: 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
91c0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
91d0: 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  rors.**.** This 
91e0: 72 6f 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69  routine identifi
91f0: 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
9200: 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
9210: 74 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  t be invoked.** 
9220: 77 68 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65  whenever an atte
9230: 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
9240: 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
9250: 61 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e  able .** that an
9260: 6f 74 68 65 72 20 74 68 72 65 61 64 20 6f 72 20  other thread or 
9270: 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b  process has lock
9280: 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75  ed..** If the bu
9290: 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
92a0: 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
92b0: 45 5f 42 55 53 59 5d 0a 2a 2a 20 28 6f 72 20 73  E_BUSY].** (or s
92c0: 6f 6d 65 74 69 6d 65 73 20 5b 53 51 4c 49 54 45  ometimes [SQLITE
92d0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 29  _IOERR_BLOCKED])
92e0: 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
92f0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
9300: 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
9310: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68  e lock..** If th
9320: 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
9330: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
9340: 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63  n the.** callbac
9350: 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  k will be invoke
9360: 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
9370: 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69  ents.  The.** fi
9380: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
9390: 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61  the handler is a
93a0: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
93b0: 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
93c0: 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
93d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
93e0: 73 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 65 20  s routine.  The 
93f0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
9400: 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  to.** the handle
9410: 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  r is the number 
9420: 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
9430: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
9440: 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
9450: 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
9460: 69 6e 67 20 65 76 65 6e 74 2e 20 49 66 20 74 68  ing event. If th
9470: 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
9480: 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
9490: 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
94a0: 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
94b0: 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
94c0: 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
94d0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
94e0: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
94f0: 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
9500: 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  rned..** If the 
9510: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
9520: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
9530: 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 20  another attempt 
9540: 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
9550: 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
9560: 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
9570: 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
9580: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
9590: 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
95a0: 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
95b0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 0a   guarantee that.
95c0: 2a 2a 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  ** it will be in
95d0: 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 72 65  voked when there
95e0: 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
95f0: 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74  ion..** If SQLit
9600: 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
9610: 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
9620: 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  usy handler coul
9630: 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61  d result in.** a
9640: 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
9650: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
9660: 45 5f 42 55 53 59 5d 20 69 6e 73 74 65 61 64 2e  E_BUSY] instead.
9670: 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
9680: 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
9690: 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
96a0: 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
96b0: 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
96c0: 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
96d0: 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
96e0: 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
96f0: 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
9700: 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
9710: 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
9720: 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
9730: 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
9740: 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
9750: 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
9760: 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
9770: 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
9780: 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
9790: 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
97a0: 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
97b0: 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
97c0: 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
97d0: 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
97e0: 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
97f0: 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
9800: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
9810: 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
9820: 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
9830: 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
9840: 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
9850: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
9860: 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
9870: 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
9880: 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
9890: 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
98a0: 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
98b0: 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
98c0: 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
98d0: 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
98e0: 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
98f0: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
9900: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
9910: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
9920: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
9930: 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
9940: 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
9950: 52 5f 42 4c 4f 43 4b 45 44 5d 20 77 68 65 6e 0a  R_BLOCKED] when.
9960: 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  ** SQLite is in 
9970: 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
9980: 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
9990: 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
99a0: 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
99b0: 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
99c0: 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
99d0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
99e0: 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
99f0: 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
9a00: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
9a10: 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
9a20: 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
9a30: 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
9a40: 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
9a50: 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
9a60: 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
9a70: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9a80: 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
9a90: 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
9aa0: 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20  readers.  If it 
9ab0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
9ac0: 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
9ad0: 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
9ae0: 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
9af0: 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
9b00: 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
9b10: 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
9b20: 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
9b30: 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
9b40: 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
9b50: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
9b60: 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
9b70: 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
9b80: 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68  RR_BLOCKED].  Th
9b90: 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
9ba0: 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
9bb0: 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
9bc0: 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
9bd0: 68 61 6e 67 65 73 2e 20 53 65 65 20 74 68 65 0a  hanges. See the.
9be0: 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70  ** <a href="http
9bf0: 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72  ://www.sqlite.or
9c00: 67 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  g/cvstrac/wiki?p
9c10: 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
9c20: 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
9c30: 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
9c40: 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
9c50: 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
9c60: 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
9c70: 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
9c80: 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a   important..**..
9c90: 2a 2a 20 53 71 6c 69 74 65 20 69 73 20 72 65 2d  ** Sqlite is re-
9ca0: 65 6e 74 72 61 6e 74 2c 20 73 6f 20 74 68 65 20  entrant, so the 
9cb0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79  busy handler may
9cc0: 20 73 74 61 72 74 20 61 20 6e 65 77 20 71 75 65   start a new que
9cd0: 72 79 2e 20 0a 2a 2a 20 28 49 74 20 69 73 20 6e  ry. .** (It is n
9ce0: 6f 74 20 63 6c 65 61 72 20 77 68 79 20 61 6e 79  ot clear why any
9cf0: 6f 6e 65 20 77 6f 75 6c 64 20 65 76 65 72 79 20  one would every 
9d00: 77 61 6e 74 20 74 6f 20 64 6f 20 74 68 69 73 2c  want to do this,
9d10: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 61 6c   but it.** is al
9d20: 6c 6f 77 65 64 2c 20 69 6e 20 74 68 65 6f 72 79  lowed, in theory
9d30: 2e 29 20 20 42 75 74 20 74 68 65 20 62 75 73 79  .)  But the busy
9d40: 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 6e 6f 74   handler may not
9d50: 20 63 6c 6f 73 65 20 74 68 65 0a 2a 2a 20 64 61   close the.** da
9d60: 74 61 62 61 73 65 2e 20 20 43 6c 6f 73 69 6e 67  tabase.  Closing
9d70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
9d80: 6f 6d 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  om a busy handle
9d90: 72 20 77 69 6c 6c 20 64 65 6c 65 74 65 20 0a 2a  r will delete .*
9da0: 2a 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  * data structure
9db0: 73 20 6f 75 74 20 66 72 6f 6d 20 75 6e 64 65 72  s out from under
9dc0: 20 74 68 65 20 65 78 65 63 75 74 69 6e 67 20 71   the executing q
9dd0: 75 65 72 79 20 61 6e 64 20 77 69 6c 6c 20 0a 2a  uery and will .*
9de0: 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 73 75 6c  * probably resul
9df0: 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
9e00: 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
9e10: 65 72 20 72 75 6e 74 69 6d 65 20 65 72 72 6f 72  er runtime error
9e20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
9e30: 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
9e40: 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
9e50: 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
9e60: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9e70: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 74 69 6e  nection.  Settin
9e80: 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
9e90: 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 20  dler clears any 
9ea0: 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e 0a 2a 2a  previous one..**
9eb0: 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69   Note that calli
9ec0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
9ed0: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 69 6c 6c  _timeout()] will
9ee0: 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
9ef0: 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  ar.** the busy h
9f00: 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68  andler..**.** Wh
9f10: 65 6e 20 6f 70 65 72 61 74 69 6e 67 20 69 6e 20  en operating in 
9f20: 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
9f30: 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20 73  shared_cache | s
9f40: 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
9f50: 5d 2c 0a 2a 2a 20 6f 6e 6c 79 20 61 20 73 69 6e  ],.** only a sin
9f60: 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
9f70: 20 63 61 6e 20 62 65 20 64 65 66 69 6e 65 64 20   can be defined 
9f80: 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73  for each databas
9f90: 65 20 66 69 6c 65 2e 0a 2a 2a 20 53 6f 20 69 66  e file..** So if
9fa0: 20 74 77 6f 20 64 61 74 61 62 61 73 65 20 63 6f   two database co
9fb0: 6e 6e 65 63 74 69 6f 6e 73 20 73 68 61 72 65 20  nnections share 
9fc0: 61 20 73 69 6e 67 6c 65 20 63 61 63 68 65 2c 20  a single cache, 
9fd0: 74 68 65 6e 20 63 68 61 6e 67 69 6e 67 0a 2a 2a  then changing.**
9fe0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
9ff0: 72 20 6f 6e 20 6f 6e 65 20 63 6f 6e 6e 65 63 74  r on one connect
a000: 69 6f 6e 20 77 69 6c 6c 20 61 6c 73 6f 20 63 68  ion will also ch
a010: 61 6e 67 65 20 74 68 65 20 62 75 73 79 0a 2a 2a  ange the busy.**
a020: 20 68 61 6e 64 6c 65 72 20 69 6e 20 74 68 65 20   handler in the 
a030: 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e  other connection
a040: 2e 20 20 54 68 65 20 62 75 73 79 20 68 61 6e 64  .  The busy hand
a050: 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  ler is invoked.*
a060: 2a 20 69 6e 20 74 68 65 20 74 68 72 65 61 64 20  * in the thread 
a070: 74 68 61 74 20 77 61 73 20 72 75 6e 6e 69 6e 67  that was running
a080: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   when the SQLITE
a090: 5f 42 55 53 59 20 77 61 73 20 68 69 74 2e 0a 2a  _BUSY was hit..*
a0a0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
a0b0: 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
a0c0: 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
a0d0: 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
a0e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a0f0: 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
a100: 6f 75 74 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  out.**.** This r
a110: 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 62 75  outine sets a bu
a120: 73 79 20 68 61 6e 64 6c 65 72 20 74 68 61 74 20  sy handler that 
a130: 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77 68 69  sleeps for a whi
a140: 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62  le when a.** tab
a150: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54  le is locked.  T
a160: 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20  he handler will 
a170: 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
a180: 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61  imes until .** a
a190: 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
a1a0: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
a1b0: 65 70 69 6e 67 20 68 61 76 65 20 62 65 65 6e 20  eping have been 
a1c0: 64 6f 6e 65 2e 20 20 41 66 74 65 72 0a 2a 2a 20  done.  After.** 
a1d0: 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
a1e0: 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74  s of sleeping, t
a1f0: 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
a200: 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61  ns 0 which.** ca
a210: 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
a220: 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20  ep()] to return 
a230: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
a240: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
a250: 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43  LOCKED]..**.** C
a260: 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
a270: 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
a280: 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
a290: 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
a2a0: 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
a2b0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
a2c0: 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
a2d0: 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
a2e0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
a2f0: 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  r a particular d
a300: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
a310: 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68  ction.  If anoth
a320: 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
a330: 77 61 73 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a  was defined  .**
a340: 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
a350: 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
a360: 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
a370: 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
a380: 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
a390: 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
a3a0: 6c 65 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  leared..*/.int s
a3b0: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
a3c0: 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
a3d0: 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
a3e0: 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
a3f0: 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
a400: 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
a410: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6e 65 78 74  .**.** This next
a420: 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 63 6f   routine is a co
a430: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
a440: 72 20 61 72 6f 75 6e 64 20 5b 73 71 6c 69 74 65  r around [sqlite
a450: 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2a 20 49 6e  3_exec()]..** In
a460: 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
a470: 67 20 61 20 75 73 65 72 2d 73 75 70 70 6c 69 65  g a user-supplie
a480: 64 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 20 65  d callback for e
a490: 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a  ach row of the.*
a4a0: 2a 20 72 65 73 75 6c 74 2c 20 74 68 69 73 20 72  * result, this r
a4b0: 6f 75 74 69 6e 65 20 72 65 6d 65 6d 62 65 72 73  outine remembers
a4c0: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65   each row of the
a4d0: 20 72 65 73 75 6c 74 20 69 6e 20 6d 65 6d 6f 72   result in memor
a4e0: 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72  y.** obtained fr
a4f0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
a500: 6f 63 28 29 5d 2c 20 74 68 65 6e 20 72 65 74 75  oc()], then retu
a510: 72 6e 73 20 61 6c 6c 20 6f 66 20 74 68 65 20 72  rns all of the r
a520: 65 73 75 6c 74 20 61 66 74 65 72 20 74 68 65 0a  esult after the.
a530: 2a 2a 20 71 75 65 72 79 20 68 61 73 20 66 69 6e  ** query has fin
a540: 69 73 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 41 73  ished. .**.** As
a550: 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 73 75 70   an example, sup
a560: 70 6f 73 65 20 74 68 65 20 71 75 65 72 79 20 72  pose the query r
a570: 65 73 75 6c 74 20 77 68 65 72 65 20 74 68 69 73  esult where this
a580: 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62   table:.**.** <b
a590: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
a5a0: 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
a5b0: 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
a5c0: 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
a5d0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
a5e0: 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
a5f0: 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
a600: 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
a610: 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
a620: 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
a630: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
a640: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uote>.**.** If t
a650: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
a660: 77 65 72 65 20 26 61 7a 52 65 73 75 6c 74 20 74  were &azResult t
a670: 68 65 6e 20 61 66 74 65 72 20 74 68 65 20 66 75  hen after the fu
a680: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a  nction returns.*
a690: 2a 20 61 7a 52 65 73 75 6c 74 20 77 69 6c 6c 20  * azResult will 
a6a0: 63 6f 6e 74 61 69 6e 20 74 68 65 20 66 6f 6c 6c  contain the foll
a6b0: 6f 77 69 6e 67 20 64 61 74 61 3a 0a 2a 2a 0a 2a  owing data:.**.*
a6c0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
a6d0: 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
a6e0: 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
a6f0: 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
a700: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
a710: 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
a720: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
a730: 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
a740: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
a750: 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
a760: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
a770: 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
a780: 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
a790: 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
a7a0: 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
a7b0: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
a7c0: 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
a7d0: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
a7e0: 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
a7f0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
a800: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 69 63  ote>.**.** Notic
a810: 65 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  e that there is 
a820: 61 6e 20 65 78 74 72 61 20 72 6f 77 20 6f 66 20  an extra row of 
a830: 64 61 74 61 20 63 6f 6e 74 61 69 6e 69 6e 67 20  data containing 
a840: 74 68 65 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 68 65  the column.** he
a850: 61 64 65 72 73 2e 20 20 42 75 74 20 74 68 65 20  aders.  But the 
a860: 2a 6e 72 6f 77 20 72 65 74 75 72 6e 20 76 61 6c  *nrow return val
a870: 75 65 20 69 73 20 73 74 69 6c 6c 20 33 2e 20 20  ue is still 3.  
a880: 2a 6e 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 73  *ncolumn is.** s
a890: 65 74 20 74 6f 20 32 2e 20 20 49 6e 20 67 65 6e  et to 2.  In gen
a8a0: 65 72 61 6c 2c 20 74 68 65 20 6e 75 6d 62 65 72  eral, the number
a8b0: 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 73 65 72   of values inser
a8c0: 74 65 64 20 69 6e 74 6f 20 61 7a 52 65 73 75 6c  ted into azResul
a8d0: 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 28 28 2a  t.** will be ((*
a8e0: 6e 72 6f 77 29 20 2b 20 31 29 2a 28 2a 6e 63 6f  nrow) + 1)*(*nco
a8f0: 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  lumn)..**.** Aft
a900: 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  er the calling f
a910: 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  unction has fini
a920: 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72  shed using the r
a930: 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64  esult, it should
a940: 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 72 65   .** pass the re
a950: 73 75 6c 74 20 64 61 74 61 20 70 6f 69 6e 74 65  sult data pointe
a960: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
a970: 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
a980: 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73  er to .** releas
a990: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
a9a0: 74 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e  t was malloc-ed.
a9b0: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
a9c0: 20 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71   way the .** [sq
a9d0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
a9e0: 68 61 70 70 65 6e 73 2c 20 74 68 65 20 63 61 6c  happens, the cal
a9f0: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ling function mu
aa00: 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
aa10: 6c 6c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ll .** [sqlite3_
aa20: 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
aa30: 2e 20 20 4f 6e 6c 79 20 5b 73 71 6c 69 74 65 33  .  Only [sqlite3
aa40: 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
aa50: 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
aa60: 65 20 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  e .** the memory
aa70: 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
aa80: 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
aa90: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
aaa0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
aab0: 74 68 65 20 73 61 6d 65 20 61 73 20 66 72 6f 6d  the same as from
aac0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
aad0: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
aae0: 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
aaf0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
ab00: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
ab10: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
ab20: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
ab30: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
ab40: 62 65 20 65 78 65 63 75 74 65 64 20 2a 2f 0a 20  be executed */. 
ab50: 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74 70   char ***resultp
ab60: 2c 20 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c  ,       /* Resul
ab70: 74 20 77 72 69 74 74 65 6e 20 74 6f 20 61 20 63  t written to a c
ab80: 68 61 72 20 2a 5b 5d 20 20 74 68 61 74 20 74 68  har *[]  that th
ab90: 69 73 20 70 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a  is points to */.
aba0: 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20    int *nrow,    
abb0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
abc0: 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
abd0: 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
abe0: 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e  /.  int *ncolumn
abf0: 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  ,          /* Nu
ac00: 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
ac10: 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
ac20: 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
ac30: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
ac40: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
ac50: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
ac60: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
ac70: 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
ac80: 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
ac90: 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
aca0: 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
acb0: 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
acc0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
acd0: 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
ace0: 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
acf0: 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
ad00: 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
ad10: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
ad20: 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
ad30: 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
ad40: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
ad50: 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
ad60: 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
ad70: 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
ad80: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
ad90: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
ada0: 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
adb0: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
adc0: 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
add0: 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
ade0: 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
adf0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
ae00: 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20    Both routines 
ae10: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
ae20: 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
ae30: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
ae40: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
ae50: 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
ae60: 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
ae70: 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
ae80: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c  ng..**.** In sql
ae90: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
aea0: 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
aeb0: 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
aec0: 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
aed0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
aee0: 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
aef0: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
af00: 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
af10: 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
af20: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
af30: 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
af40: 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
af50: 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 4e 6f  t parameter.  No
af60: 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
af70: 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
af80: 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
af90: 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
afa0: 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
afb0: 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
afc0: 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
afd0: 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
afe0: 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
aff0: 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
b000: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
b010: 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
b020: 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
b030: 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
b040: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
b050: 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
b060: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
b070: 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
b080: 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
b090: 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
b0a0: 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
b0b0: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
b0c0: 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
b0d0: 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
b0e0: 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
b0f0: 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
b100: 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
b110: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
b120: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
b130: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
b140: 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
b150: 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
b160: 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
b170: 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
b180: 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
b190: 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
b1a0: 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
b1b0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
b1c0: 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
b1d0: 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
b1e0: 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
b1f0: 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
b200: 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
b210: 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
b220: 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
b230: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
b240: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
b250: 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
b260: 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
b270: 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
b280: 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
b290: 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
b2a0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
b2b0: 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
b2c0: 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
b2d0: 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
b2e0: 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
b2f0: 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
b300: 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
b310: 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
b320: 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
b330: 74 66 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  tf formatting op
b340: 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
b350: 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
b360: 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
b370: 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
b380: 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  options..**.** T
b390: 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
b3a0: 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
b3b0: 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
b3c0: 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
b3d0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
b3e0: 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
b3f0: 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
b400: 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
b410: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
b420: 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
b430: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
b440: 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
b450: 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  al.  By doubling
b460: 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
b470: 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
b480: 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
b490: 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
b4a0: 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
b4b0: 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
b4c0: 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
b4d0: 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74  mple, so some st
b4e0: 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 63 6f  ring variable co
b4f0: 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
b500: 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
b510: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
b520: 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
b530: 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
b540: 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
b550: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
b560: 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
b570: 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
b580: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
b590: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
b5a0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
b5b0: 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
b5c0: 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
b5d0: 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
b5e0: 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
b5f0: 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
b600: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
b610: 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
b620: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
b630: 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
b640: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
b650: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
b660: 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
b670: 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
b680: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
b690: 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
b6a0: 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
b6b0: 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
b6c0: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
b6d0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
b6e0: 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
b6f0: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
b700: 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
b710: 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
b720: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
b730: 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
b740: 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
b750: 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
b760: 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
b770: 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
b780: 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
b790: 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
b7a0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
b7b0: 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
b7c0: 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
b7d0: 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
b7e0: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
b7f0: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
b800: 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
b810: 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
b820: 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
b830: 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
b840: 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77  ou.** should alw
b850: 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
b860: 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
b870: 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
b880: 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c  o a string .** l
b890: 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  iteral..**.** Th
b8a0: 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
b8b0: 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
b8c0: 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
b8d0: 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
b8e0: 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
b8f0: 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
b900: 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20 74 68  tring.  Or if th
b910: 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
b920: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c  he argument.** l
b930: 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
b940: 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
b950: 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
b960: 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 20 73  NULL" (without s
b970: 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29  ingle.** quotes)
b980: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
b990: 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c   %Q option.  So,
b9a0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
b9b0: 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
b9c0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
b9d0: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
b9e0: 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
b9f0: 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
ba00: 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
ba10: 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
ba20: 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
ba30: 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
ba40: 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
ba50: 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
ba60: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
ba70: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
ba80: 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
ba90: 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
baa0: 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
bab0: 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
bac0: 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
bad0: 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
bae0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
baf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20  .**.** The "%z" 
bb00: 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
bb10: 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20  n works exactly 
bb20: 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74  like "%s" with t
bb30: 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
bb40: 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
bb50: 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
bb60: 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
bb70: 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
bb80: 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
bb90: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
bba0: 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
bbb0: 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..*/.char *sqlit
bbc0: 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
bbd0: 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
bbe0: 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
bbf0: 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
bc00: 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
bc10: 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
bc20: 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
bc30: 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a  t char*, ...);..
bc40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
bc50: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
bc60: 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
bc70: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
bc80: 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
bc90: 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
bca0: 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
bcb0: 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
bcc0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
bcd0: 64 73 2e 20 28 53 65 65 20 74 68 65 20 65 78 63  ds. (See the exc
bce0: 65 70 74 69 6f 6e 20 62 65 6c 6f 77 2e 29 0a 2a  eption below.).*
bcf0: 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d  * The default im
bd00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
bd10: 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  of the memory al
bd20: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
bd30: 65 6d 20 75 73 65 73 20 74 68 65 20 6d 61 6c 6c  em uses the mall
bd40: 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 0a  oc(), realloc().
bd50: 2a 2a 20 61 6e 64 20 66 72 65 65 28 29 20 70 72  ** and free() pr
bd60: 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74  ovided by the st
bd70: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
bd80: 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 0a  .  However, if .
bd90: 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  ** SQLite is com
bda0: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 66  piled with the f
bdb0: 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72 65 70 72  ollowing C prepr
bdc0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a  ocessor macro.**
bdd0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
bde0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
bdf0: 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 3c  ORY_ALLOCATION <
be00: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
be10: 2a 2a 20 74 68 65 6e 20 6e 6f 20 69 6d 70 6c 65  ** then no imple
be20: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 70 72 6f  mentation is pro
be30: 76 69 64 65 64 20 66 6f 72 20 74 68 65 73 65 20  vided for these 
be40: 72 6f 75 74 69 6e 65 73 20 62 79 0a 2a 2a 20 53  routines by.** S
be50: 51 4c 69 74 65 2e 20 20 54 68 65 20 61 70 70 6c  QLite.  The appl
be60: 69 63 61 74 69 6f 6e 20 74 68 61 74 20 6c 69 6e  ication that lin
be70: 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74  ks against SQLit
be80: 65 20 69 73 0a 2a 2a 20 65 78 70 65 63 74 65 64  e is.** expected
be90: 20 74 6f 20 70 72 6f 76 69 64 65 20 69 74 73 20   to provide its 
bea0: 6f 77 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  own implementati
beb0: 6f 6e 2e 20 20 49 66 20 74 68 65 20 61 70 70 6c  on.  If the appl
bec0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20  ication.** does 
bed0: 70 72 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20  provide its own 
bee0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
bef0: 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
bf00: 73 2c 20 74 68 65 6e 0a 2a 2a 20 69 74 20 6d 75  s, then.** it mu
bf10: 73 74 20 61 6c 73 6f 20 70 72 6f 76 69 64 65 20  st also provide 
bf20: 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
bf30: 6e 73 20 66 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ns for.** [sqlit
bf40: 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
bf50: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  )], [sqlite3_mem
bf60: 6f 72 79 5f 75 73 65 64 28 29 5d 2c 20 61 6e 64  ory_used()], and
bf70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
bf80: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
bf90: 2e 20 20 54 68 65 20 61 6c 74 65 72 6e 61 74 69  .  The alternati
bfa0: 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
bfb0: 6e 73 0a 2a 2a 20 66 6f 72 20 74 68 65 73 65 20  ns.** for these 
bfc0: 6c 61 73 74 20 74 68 72 65 65 20 72 6f 75 74 69  last three routi
bfd0: 6e 65 73 20 6e 65 65 64 20 6e 6f 74 20 61 63 74  nes need not act
bfe0: 75 61 6c 6c 79 20 77 6f 72 6b 2c 20 62 75 74 0a  ually work, but.
bff0: 2a 2a 20 73 74 75 62 20 66 75 6e 63 74 69 6f 6e  ** stub function
c000: 73 20 61 74 20 6c 65 61 73 74 20 61 72 65 20 6e  s at least are n
c010: 65 65 64 65 64 20 74 6f 20 73 74 61 74 69 73 66  eeded to statisf
c020: 79 20 74 68 65 20 6c 69 6e 6b 65 72 2e 0a 2a 2a  y the linker..**
c030: 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20 63 61   SQLite never ca
c040: 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  lls [sqlite3_mem
c050: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
c060: 20 69 74 73 65 6c 66 2c 20 62 75 74 0a 2a 2a 20   itself, but.** 
c070: 74 68 65 20 73 79 6d 62 6f 6c 20 69 73 20 69 6e  the symbol is in
c080: 63 6c 75 64 65 64 20 69 6e 20 61 20 74 61 62 6c  cluded in a tabl
c090: 65 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  e as part of the
c0a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  .** [sqlite3_loa
c0b0: 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69  d_extension()] i
c0c0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 0a 2a  nterface.  The.*
c0d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
c0e0: 79 5f 61 6c 61 72 6d 28 29 5d 20 61 6e 64 20 5b  y_alarm()] and [
c0f0: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
c100: 73 65 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  sed()] interface
c110: 73 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  s.** are called 
c120: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  by [sqlite3_soft
c130: 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 20 61  _heap_limit()] a
c140: 6e 64 20 77 6f 72 6b 69 6e 67 20 69 6d 70 6c 65  nd working imple
c150: 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66  mentations.** of
c160: 20 62 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 6d   both routines m
c170: 75 73 74 20 62 65 20 70 72 6f 76 69 64 65 64 20  ust be provided 
c180: 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  if [sqlite3_soft
c190: 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a  _heap_limit()].*
c1a0: 2a 20 69 73 20 74 6f 20 6f 70 65 72 61 74 65 20  * is to operate 
c1b0: 63 6f 72 72 65 63 74 6c 79 2e 0a 2a 2a 0a 2a 2a  correctly..**.**
c1c0: 20 3c 62 3e 45 78 63 65 70 74 69 6f 6e 3a 3c 2f   <b>Exception:</
c1d0: 62 3e 20 54 68 65 20 77 69 6e 64 6f 77 73 20 4f  b> The windows O
c1e0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
c1f0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
c200: 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
c210: 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
c220: 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
c230: 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
c240: 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
c250: 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
c260: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
c270: 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
c280: 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
c290: 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
c2a0: 63 75 6c 61 72 20 77 69 6e 64 6f 77 73 0a 2a 2a  cular windows.**
c2b0: 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
c2c0: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
c2d0: 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
c2e0: 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
c2f0: 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
c300: 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
c310: 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
c320: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
c330: 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
c340: 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 76 6f  TE_NOMEM]..*/.vo
c350: 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
c360: 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
c370: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
c380: 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
c390: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
c3a0: 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
c3b0: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
c3c0: 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
c3d0: 63 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64 64 69  cs.**.** In addi
c3e0: 74 69 6f 6e 20 74 6f 20 74 68 65 20 62 61 73 69  tion to the basi
c3f0: 63 20 74 68 72 65 65 20 61 6c 6c 6f 63 61 74 69  c three allocati
c400: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20  on routines .** 
c410: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
c420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
c430: 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
c440: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  e3_realloc()],.*
c450: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
c460: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
c470: 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20  m included with 
c480: 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 73 6f  the SQLite.** so
c490: 75 72 63 65 73 20 70 72 6f 76 69 64 65 73 20 74  urces provides t
c4a0: 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 68  he interfaces sh
c4b0: 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 0a 2a 2a  own below..**.**
c4c0: 20 54 68 65 20 66 69 72 73 74 20 6f 66 20 74 68   The first of th
c4d0: 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
c4e0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 6d 6f   returns the amo
c4f0: 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 0a 2a  unt of memory .*
c500: 2a 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  * currently outs
c510: 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
c520: 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
c530: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  .  The second.**
c540: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 61 72   returns the lar
c550: 67 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f  gest instantaneo
c560: 75 73 20 61 6d 6f 75 6e 74 20 6f 66 20 6f 75 74  us amount of out
c570: 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 6d 65 6d 6f  standing.** memo
c580: 72 79 2e 20 20 54 68 65 20 68 69 67 68 77 61 74  ry.  The highwat
c590: 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
c5a0: 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
c5b0: 20 69 73 0a 2a 2a 20 74 72 75 65 2e 0a 2a 2a 0a   is.** true..**.
c5c0: 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
c5d0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
c5e0: 6f 75 74 69 6e 65 73 20 69 6e 20 74 68 65 20 53  outines in the S
c5f0: 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 69 73  QLite core.** is
c600: 20 6f 6d 69 74 74 65 64 20 69 66 20 74 68 65 20   omitted if the 
c610: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 63  application is c
c620: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
c630: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  .** SQLITE_OMIT_
c640: 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
c650: 4e 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  N macro defined.
c660: 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 0a    In that case,.
c670: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
c680: 6f 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 53 51  on that links SQ
c690: 4c 69 74 65 20 6d 75 73 74 20 70 72 6f 76 69 64  Lite must provid
c6a0: 65 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 61 6c 74  e its own.** alt
c6b0: 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65  ernative impleme
c6c0: 6e 74 61 74 69 6f 6e 2e 20 20 53 65 65 20 74 68  ntation.  See th
c6d0: 65 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  e documentation 
c6e0: 6f 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  on.** [sqlite3_m
c6f0: 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 61 64 64  alloc()] for add
c700: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
c710: 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ion..*/.sqlite3_
c720: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
c730: 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
c740: 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
c750: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
c760: 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
c770: 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
c780: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
c790: 41 6c 6c 6f 63 61 74 69 6f 6e 20 41 6c 61 72 6d  Allocation Alarm
c7a0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
c7b0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
c7c0: 6d 5d 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  m] routine is us
c7d0: 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a  ed to register.*
c7e0: 2a 20 61 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  * a callback on 
c7f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c800: 6e 20 65 76 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  n events..**.** 
c810: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
c820: 69 73 74 65 72 73 20 6f 72 20 63 6c 65 61 72 73  isters or clears
c830: 20 61 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61   a callbacks tha
c840: 74 20 66 69 72 65 73 20 77 68 65 6e 0a 2a 2a 20  t fires when.** 
c850: 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  the amount of me
c860: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 65  mory allocated e
c870: 78 63 65 65 64 73 20 69 54 68 72 65 73 68 6f 6c  xceeds iThreshol
c880: 64 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 61 20 73 69  d.  Only.** a si
c890: 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 61  ngle callback ca
c8a0: 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
c8b0: 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
c8c0: 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
c8d0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
c8e0: 6d 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20  m()] overwrites 
c8f0: 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
c900: 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 61  lback..** The ca
c910: 6c 6c 62 61 63 6b 20 69 73 20 64 69 73 61 62 6c  llback is disabl
c920: 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 78 43  ed by setting xC
c930: 61 6c 6c 62 61 63 6b 20 74 6f 20 61 20 4e 55 4c  allback to a NUL
c940: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  L.** pointer..**
c950: 20 0a 2a 2a 20 54 68 65 20 70 61 72 61 6d 65 74   .** The paramet
c960: 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ers to the callb
c970: 61 63 6b 20 61 72 65 20 74 68 65 20 70 41 72 67  ack are the pArg
c980: 20 76 61 6c 75 65 2c 20 74 68 65 20 0a 2a 2a 20   value, the .** 
c990: 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
c9a0: 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73   currently in us
c9b0: 65 2c 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20  e, and the size 
c9c0: 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61  of the.** alloca
c9d0: 74 69 6f 6e 20 74 68 61 74 20 70 72 6f 76 6f 6b  tion that provok
c9e0: 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  ed the callback.
c9f0: 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 77    The callback w
ca00: 69 6c 6c 0a 2a 2a 20 70 72 65 73 75 6d 61 62 6c  ill.** presumabl
ca10: 79 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  y invoke [sqlite
ca20: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65  3_free()] to fre
ca30: 65 20 75 70 20 6d 65 6d 6f 72 79 20 73 70 61 63  e up memory spac
ca40: 65 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  e..** The callba
ca50: 63 6b 20 6d 61 79 20 69 6e 76 6f 6b 65 20 5b 73  ck may invoke [s
ca60: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
ca70: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
ca80: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 62 75 74 20 69  lloc()].** but i
ca90: 66 20 69 74 20 64 6f 65 73 2c 20 6e 6f 20 61 64  f it does, no ad
caa0: 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63  ditional callbac
cab0: 6b 73 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  ks will be invok
cac0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 72 65 63  ed by.** the rec
cad0: 75 72 73 69 76 65 20 63 61 6c 6c 73 2e 0a 2a 2a  ursive calls..**
cae0: 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
caf0: 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
cb00: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f  ()] interface wo
cb10: 72 6b 73 20 62 79 20 72 65 67 69 73 74 65 72 69  rks by registeri
cb20: 6e 67 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  ng.** a memory a
cb30: 6c 61 72 6d 20 61 74 20 74 68 65 20 73 6f 66 74  larm at the soft
cb40: 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20   heap limit and 
cb50: 69 6e 76 6f 6b 69 6e 67 20 0a 2a 2a 20 5b 73 71  invoking .** [sq
cb60: 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
cb70: 6d 6f 72 79 28 29 5d 20 69 6e 20 74 68 65 20 61  mory()] in the a
cb80: 6c 61 72 6d 20 63 61 6c 6c 62 61 63 6b 2e 20 20  larm callback.  
cb90: 41 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 70  Application.** p
cba0: 72 6f 67 72 61 6d 73 20 73 68 6f 75 6c 64 20 6e  rograms should n
cbb0: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ot attempt to us
cbc0: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  e the [sqlite3_m
cbd0: 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 0a 2a  emory_alarm()].*
cbe0: 2a 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 61  * interface beca
cbf0: 75 73 65 20 64 6f 69 6e 67 20 73 6f 20 77 69 6c  use doing so wil
cc00: 6c 20 69 6e 74 65 72 66 65 72 65 20 77 69 74 68  l interfere with
cc10: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
cc20: 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
cc30: 28 29 5d 20 6d 6f 64 75 6c 65 2e 20 20 54 68 69  ()] module.  Thi
cc40: 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  s interface is e
cc50: 78 70 6f 73 65 64 0a 2a 2a 20 6f 6e 6c 79 20 73  xposed.** only s
cc60: 6f 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  o that applicati
cc70: 6f 6e 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20  ons can provide 
cc80: 74 68 65 69 72 20 6f 77 6e 0a 2a 2a 20 61 6c 74  their own.** alt
cc90: 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65  ernative impleme
cca0: 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
ccb0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69 73 0a   SQLite core is.
ccc0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
ccd0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
cce0: 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 2e 0a  ORY_ALLOCATION..
ccf0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  */.int sqlite3_m
cd00: 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 0a 20 20 76  emory_alarm(.  v
cd10: 6f 69 64 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28  oid(*xCallback)(
cd20: 76 6f 69 64 20 2a 70 41 72 67 2c 20 73 71 6c 69  void *pArg, sqli
cd30: 74 65 33 5f 69 6e 74 36 34 20 75 73 65 64 2c 20  te3_int64 used, 
cd40: 69 6e 74 20 4e 29 2c 0a 20 20 76 6f 69 64 20 2a  int N),.  void *
cd50: 70 41 72 67 2c 0a 20 20 73 71 6c 69 74 65 33 5f  pArg,.  sqlite3_
cd60: 69 6e 74 36 34 20 69 54 68 72 65 73 68 6f 6c 64  int64 iThreshold
cd70: 0a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  .);.../*.** CAPI
cd80: 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
cd90: 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
cda0: 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 2a 0a 2a   Callbacks.***.*
cdb0: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
cdc0: 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
cdd0: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
cde0: 69 74 68 20 74 68 65 20 53 51 4c 69 74 65 20 6c  ith the SQLite l
cdf0: 69 62 72 61 72 79 2e 20 20 0a 2a 2a 20 54 68 65  ibrary.  .** The
ce00: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
ce10: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
ce20: 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
ce30: 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
ce40: 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
ce50: 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
ce60: 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
ce70: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
ce80: 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
ce90: 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
cea0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
ceb0: 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41  pare16_v2()].  A
cec0: 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
ced0: 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
cee0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
cef0: 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
cf00: 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
cf10: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
cf20: 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
cf30: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
cf40: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
cf50: 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
cf60: 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
cf70: 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74  llowed.  The aut
cf80: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
cf90: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
cfa0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 74 6f 20 61  n SQLITE_OK to a
cfb0: 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
cfc0: 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
cfd0: 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
cfe0: 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
cff0: 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
d000: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
d010: 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
d020: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
d030: 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
d040: 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
d050: 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
d060: 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
d070: 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
d080: 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 44 65 70 65 6e  r.  .**.** Depen
d090: 64 69 6e 67 20 6f 6e 20 74 68 65 20 61 63 74 69  ding on the acti
d0a0: 6f 6e 2c 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  on, the [SQLITE_
d0b0: 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c  IGNORE] and [SQL
d0c0: 49 54 45 5f 44 45 4e 59 5d 20 72 65 74 75 72 6e  ITE_DENY] return
d0d0: 0a 2a 2a 20 63 6f 64 65 73 20 6d 69 67 68 74 20  .** codes might 
d0e0: 6d 65 61 6e 20 73 6f 6d 65 74 68 69 6e 67 20 64  mean something d
d0f0: 69 66 66 65 72 65 6e 74 20 6f 72 20 74 68 65 79  ifferent or they
d100: 20 6d 69 67 68 74 20 6d 65 61 6e 20 74 68 65 20   might mean the 
d110: 73 61 6d 65 0a 2a 2a 20 74 68 69 6e 67 2e 20 20  same.** thing.  
d120: 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  If the action is
d130: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
d140: 6f 20 70 65 72 66 6f 72 6d 20 61 20 64 65 6c 65  o perform a dele
d150: 74 65 20 6f 70 65 72 74 69 6f 6e 2c 0a 2a 2a 20  te opertion,.** 
d160: 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  then [SQLITE_IGN
d170: 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  ORE] and [SQLITE
d180: 5f 44 45 4e 59 5d 20 62 6f 74 68 20 63 61 75 73  _DENY] both caus
d190: 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
d1a0: 63 6f 6d 70 69 6c 61 74 69 6f 6e 0a 2a 2a 20 74  compilation.** t
d1b0: 6f 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  o fail with an e
d1c0: 72 72 6f 72 2e 20 20 42 75 74 20 69 66 20 74 68  rror.  But if th
d1d0: 65 20 61 63 74 69 6f 6e 20 69 73 20 74 6f 20 72  e action is to r
d1e0: 65 61 64 20 61 20 73 70 65 63 69 66 69 63 20 63  ead a specific c
d1f0: 6f 6c 75 6d 6e 0a 2a 2a 20 66 72 6f 6d 20 61 20  olumn.** from a 
d200: 73 70 65 63 69 66 69 63 20 74 61 62 6c 65 2c 20  specific table, 
d210: 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 44 45 4e  then [SQLITE_DEN
d220: 59 5d 20 77 69 6c 6c 20 63 61 75 73 65 20 74 68  Y] will cause th
d230: 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 74 61 74  e entire.** stat
d240: 65 6d 65 6e 74 20 74 6f 20 66 61 69 6c 20 62 75  ement to fail bu
d250: 74 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  t [SQLITE_IGNORE
d260: 5d 20 77 69 6c 6c 20 63 61 75 73 65 20 61 20 4e  ] will cause a N
d270: 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 62 65 0a  ULL value to be.
d280: 2a 2a 20 72 65 61 64 20 69 6e 73 74 65 61 64 20  ** read instead 
d290: 6f 66 20 74 68 65 20 61 63 74 75 61 6c 20 63 6f  of the actual co
d2a0: 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  lumn value..**.*
d2b0: 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
d2c0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
d2d0: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
d2e0: 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
d2f0: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
d300: 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
d310: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
d320: 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
d330: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
d340: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
d350: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
d360: 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c 49 54  teger .** [SQLIT
d370: 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
d380: 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
d390: 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75  fies the particu
d3a0: 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f  lar action.** to
d3b0: 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
d3c0: 20 54 68 65 20 61 76 61 69 6c 61 62 6c 65 20 61   The available a
d3d0: 63 74 69 6f 6e 20 63 6f 64 65 73 20 61 72 65 0a  ction codes are.
d3e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  ** [SQLITE_COPY 
d3f0: 7c 20 64 6f 63 75 6d 65 6e 74 65 64 20 73 65 70  | documented sep
d400: 61 72 61 74 65 6c 79 5d 2e 20 20 54 68 65 20 74  arately].  The t
d410: 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
d420: 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  th.** parameters
d430: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
d440: 20 61 72 65 20 73 74 72 69 6e 67 73 20 74 68 61   are strings tha
d450: 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
d460: 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
d470: 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
d480: 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
d490: 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  d..**.** An auth
d4a0: 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
d4b0: 68 65 6e 20 70 72 65 70 61 72 69 6e 67 20 53 51  hen preparing SQ
d4c0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
d4d0: 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 0a 2a  m an untrusted.*
d4e0: 2a 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  * source, to ens
d4f0: 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
d500: 20 73 74 61 74 65 6d 65 6e 74 73 20 64 6f 20 6e   statements do n
d510: 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
d520: 20 64 61 74 61 0a 2a 2a 20 74 68 61 74 20 74 68   data.** that th
d530: 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
d540: 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
d550: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 74  at they do not t
d560: 72 79 20 74 6f 0a 2a 2a 20 65 78 65 63 75 74 65  ry to.** execute
d570: 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
d580: 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
d590: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
d5a0: 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
d5b0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
d5c0: 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
d5d0: 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
d5e0: 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
d5f0: 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
d600: 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
d610: 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
d620: 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
d630: 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
d640: 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
d650: 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
d660: 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
d670: 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
d680: 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
d690: 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
d6a0: 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
d6b0: 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
d6c0: 20 69 73 20 62 65 69 6e 67 20 70 72 65 70 61 72   is being prepar
d6d0: 65 64 20 74 68 61 74 20 64 69 73 61 6c 6c 6f 77  ed that disallow
d6e0: 73 20 65 76 65 72 79 74 68 69 6e 67 0a 2a 2a 20  s everything.** 
d6f0: 65 78 63 65 70 74 20 53 45 4c 45 43 54 20 73 74  except SELECT st
d700: 61 74 65 6d 65 6e 74 73 2e 20 20 0a 2a 2a 0a 2a  atements.  .**.*
d710: 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  * Only a single 
d720: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
d730: 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
d740: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d750: 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
d760: 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
d770: 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
d780: 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
d790: 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
d7a0: 20 63 61 6c 6c 2e 20 20 41 20 4e 55 4c 4c 20 61   call.  A NULL a
d7b0: 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20  uthorizer means 
d7c0: 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a  that no authoriz
d7d0: 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
d7e0: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 54  k is invoked.  T
d7f0: 68 65 20 64 65 66 61 75 6c 74 20 61 75 74 68 6f  he default autho
d800: 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a  rizer is NULL..*
d810: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
d820: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
d830: 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
d840: 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a  d only during .*
d850: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
d860: 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
d870: 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
d880: 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
d890: 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
d8a0: 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
d8b0: 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
d8c0: 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2f 0a 69 6e  3_step()]..*/.in
d8d0: 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
d8e0: 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
d8f0: 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
d900: 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
d910: 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
d920: 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
d930: 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
d940: 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
d950: 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
d960: 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
d970: 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
d980: 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
d990: 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
d9a0: 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
d9b0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
d9c0: 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
d9d0: 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
d9e0: 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
d9f0: 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
da00: 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
da10: 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
da20: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
da30: 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
da40: 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
da50: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
da60: 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
da70: 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
da80: 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
da90: 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
daa0: 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
dab0: 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
dac0: 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
dad0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
dae0: 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
daf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
db00: 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
db10: 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
db20: 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
db30: 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
db40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
db50: 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
db60: 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
db70: 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
db80: 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
db90: 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
dba0: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
dbb0: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
dbc0: 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
dbd0: 69 7a 65 72 20 63 65 72 74 61 69 6e 20 53 51 4c  izer certain SQL
dbe0: 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
dbf0: 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
dc00: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
dc10: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
dc20: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
dc30: 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
dc40: 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
dc50: 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
dc60: 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
dc70: 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
dc80: 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
dc90: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
dca0: 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
dcb0: 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
dcc0: 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
dcd0: 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
dce0: 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
dcf0: 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a  ion is to be .**
dd00: 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
dd10: 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
dd20: 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
dd30: 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61  authorization ca
dd40: 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
dd50: 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
dd60: 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
dd70: 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
dd80: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
dd90: 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
dda0: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
ddb0: 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 72  er.  The 5th par
ddc0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
ddd0: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
dde0: 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
ddf0: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
de00: 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
de10: 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  , .** etc.) if a
de20: 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20  pplicable.  The 
de30: 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
de40: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
de50: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
de60: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
de70: 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
de80: 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
de90: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
dea0: 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
deb0: 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
dec0: 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
ded0: 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
dee0: 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d  ly from .** top-
def0: 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
df00: 2a 2f 0a 2f 2a 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 20  *************** 
df30: 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
df40: 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
df50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
df60: 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
df70: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
df80: 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
df90: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
dfa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dfb0: 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
dfc0: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
dfd0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
dfe0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
dff0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
e000: 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
e010: 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
e020: 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
e030: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
e040: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
e050: 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
e060: 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
e070: 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
e080: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
e090: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
e0a0: 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
e0b0: 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
e0c0: 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
e0d0: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
e0e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
e0f0: 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
e100: 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
e110: 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
e120: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
e130: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
e140: 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
e150: 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
e160: 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
e170: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
e180: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
e190: 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
e1a0: 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
e1b0: 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
e1c0: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
e1d0: 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
e1e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
e1f0: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
e200: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
e210: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
e220: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
e230: 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
e240: 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
e250: 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
e260: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e270: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
e280: 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
e290: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
e2a0: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
e2b0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
e2c0: 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
e2d0: 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
e2e0: 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
e2f0: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
e300: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
e310: 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
e320: 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
e330: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
e340: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
e350: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e360: 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
e370: 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
e380: 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
e390: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
e3a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e3b0: 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
e3c0: 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
e3d0: 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
e3e0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
e3f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e400: 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
e410: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
e420: 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
e430: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
e440: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e450: 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
e460: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
e470: 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
e480: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
e490: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e4a0: 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
e4b0: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
e4c0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
e4d0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
e4e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
e4f0: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
e500: 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
e510: 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
e520: 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
e530: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
e540: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
e550: 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
e560: 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
e570: 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
e580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
e590: 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
e5a0: 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
e5b0: 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
e5c0: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
e5d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
e5e0: 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
e5f0: 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   22   /* NULL   
e600: 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
e610: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
e620: 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
e630: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
e640: 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
e650: 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
e660: 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
e670: 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
e680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
e690: 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
e6a0: 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
e6b0: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
e6c0: 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
e6d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
e6e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
e6f0: 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
e700: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
e710: 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
e720: 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
e730: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
e740: 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
e750: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e760: 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
e770: 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
e780: 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
e790: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
e7a0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
e7b0: 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
e7c0: 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
e7d0: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
e7e0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
e7f0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
e800: 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
e810: 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
e820: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
e830: 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
e840: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e850: 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
e860: 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
e870: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
e880: 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
e890: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e8a0: 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
e8b0: 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
e8c0: 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
e8d0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
e8e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e8f0: 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
e900: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
e910: 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
e920: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e930: 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
e940: 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
e950: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
e960: 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
e970: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
e980: 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
e990: 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
e9a0: 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
e9b0: 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
e9c0: 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
e9d0: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
e9e0: 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
e9f0: 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
ea00: 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
ea10: 6b 65 64 0a 2a 2a 20 61 74 20 74 68 65 20 66 69  ked.** at the fi
ea20: 72 73 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rst [sqlite3_ste
ea30: 70 28 29 5d 20 66 6f 72 20 74 68 65 20 65 76 61  p()] for the eva
ea40: 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 20 53 51  luation of an SQ
ea50: 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
ea60: 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
ea70: 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
ea80: 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
ea90: 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
eaa0: 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
eab0: 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
eac0: 65 73 20 61 6e 64 20 69 6e 63 6c 75 64 65 73 0a  es and includes.
ead0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6f  ** information o
eae0: 6e 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  n how long that 
eaf0: 73 74 61 74 65 6d 65 6e 74 20 72 61 6e 2e 0a 2a  statement ran..*
eb00: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
eb10: 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69  _profile() API i
eb20: 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
eb30: 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
eb40: 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75  tal and.** is su
eb50: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e  bject to change.
eb60: 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
eb70: 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
eb80: 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
eb90: 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
eba0: 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64  *), void*);.void
ebb0: 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
ebc0: 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
ebd0: 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
ebe0: 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
ebf0: 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
ec00: 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
ec10: 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
ec20: 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
ec30: 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  cks.**.** This r
ec40: 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65  outine configure
ec50: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
ec60: 63 74 69 6f 6e 20 2d 20 74 68 65 20 70 72 6f 67  ction - the prog
ec70: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20  ress callback - 
ec80: 74 68 61 74 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  that.** is invok
ec90: 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
eca0: 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
ecb0: 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ing calls to [sq
ecc0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 0a 2a  lite3_exec()],.*
ecd0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
ece0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
ecf0: 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41  get_table()].  A
ed00: 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
ed10: 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72  r this .** inter
ed20: 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
ed30: 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
ed40: 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
ed50: 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ry..**.** The pr
ed60: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
ed70: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  is invoked once 
ed80: 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72 74  for every N virt
ed90: 75 61 6c 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f  ual machine opco
eda0: 64 65 73 2c 0a 2a 2a 20 77 68 65 72 65 20 4e 20  des,.** where N 
edb0: 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
edc0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66  gument to this f
edd0: 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 70 72 6f  unction. The pro
ede0: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a  gress callback.*
edf0: 2a 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e  * itself is iden
ee00: 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68  tified by the th
ee10: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
ee20: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54  this function. T
ee30: 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 61 72 67  he fourth.** arg
ee40: 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75  ument to this fu
ee50: 6e 63 74 69 6f 6e 20 69 73 20 61 20 76 6f 69 64  nction is a void
ee60: 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
ee70: 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  to the progress 
ee80: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
ee90: 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69  tion each time i
eea0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  t is invoked..**
eeb0: 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  .** If a call to
eec0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
eed0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
eee0: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
eef0: 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a  _get_table()].**
ef00: 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65   results in fewe
ef10: 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73  r than N opcodes
ef20: 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c   being executed,
ef30: 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
ef40: 73 73 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ss .** callback 
ef50: 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64  is never invoked
ef60: 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e 6c 79 20 61 20  ..** .** Only a 
ef70: 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
ef80: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
ef90: 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
efa0: 72 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  red for each.** 
efb0: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  open database co
efc0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 45 76 65 72 79  nnection.  Every
efd0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
efe0: 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
eff0: 72 28 29 0a 2a 2a 20 6f 76 65 72 77 72 69 74 65  r().** overwrite
f000: 73 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66  s the results of
f010: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
f020: 6c 6c 2e 0a 2a 2a 20 54 6f 20 72 65 6d 6f 76 65  ll..** To remove
f030: 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
f040: 6c 6c 62 61 63 6b 20 61 6c 74 6f 67 65 74 68 65  llback altogethe
f050: 72 2c 20 70 61 73 73 20 4e 55 4c 4c 20 61 73 20  r, pass NULL as 
f060: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
f070: 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75  ument to this fu
f080: 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
f090: 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
f0a0: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
f0b0: 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68   result other th
f0c0: 61 6e 20 30 2c 20 74 68 65 6e 20 74 68 65 20 63  an 0, then the c
f0d0: 75 72 72 65 6e 74 20 0a 2a 2a 20 71 75 65 72 79  urrent .** query
f0e0: 20 69 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20   is immediately 
f0f0: 74 65 72 6d 69 6e 61 74 65 64 20 61 6e 64 20 61  terminated and a
f100: 6e 79 20 64 61 74 61 62 61 73 65 20 63 68 61 6e  ny database chan
f110: 67 65 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  ges rolled back.
f120: 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 61 69 6e 69  .** The containi
f130: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
f140: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
f150: 65 70 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  ep()], or.** [sq
f160: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
f170: 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 20  )] call returns 
f180: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
f190: 2e 20 20 20 54 68 69 73 20 66 65 61 74 75 72 65  .   This feature
f1a0: 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
f1b0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
f1c0: 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 22   implement the "
f1d0: 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
f1e0: 6e 20 61 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20  n a.** progress 
f1f0: 64 69 61 6c 6f 67 20 62 6f 78 20 69 6e 20 61 20  dialog box in a 
f200: 47 55 49 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  GUI..*/.void sql
f210: 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
f220: 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
f230: 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
f240: 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
f250: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
f260: 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
f270: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
f280: 2a 0a 2a 2a 20 4f 70 65 6e 20 74 68 65 20 73 71  *.** Open the sq
f290: 6c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  lite database fi
f2a0: 6c 65 20 22 66 69 6c 65 6e 61 6d 65 22 2e 20 20  le "filename".  
f2b0: 54 68 65 20 22 66 69 6c 65 6e 61 6d 65 22 20 69  The "filename" i
f2c0: 73 20 55 54 46 2d 38 0a 2a 2a 20 65 6e 63 6f 64  s UTF-8.** encod
f2d0: 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ed for [sqlite3_
f2e0: 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  open()] and [sql
f2f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
f300: 61 6e 64 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  and UTF-16 encod
f310: 65 64 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ed.** in the nat
f320: 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
f330: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
f340: 31 36 28 29 5d 2e 0a 2a 2a 20 41 6e 20 5b 73 71  16()]..** An [sq
f350: 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 69  lite3*] handle i
f360: 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  s returned in *p
f370: 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20  pDb, even.** if 
f380: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
f390: 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
f3a0: 20 69 73 20 6f 70 65 6e 65 64 20 28 6f 72 20 63   is opened (or c
f3b0: 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
f3c0: 75 6c 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53  ully,.** then [S
f3d0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
f3e0: 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65  urned. Otherwise
f3f0: 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
f400: 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 0a  s returned. The.
f410: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
f420: 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
f430: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 20 72  3_errmsg16()]  r
f440: 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
f450: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
f460: 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
f470: 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
f480: 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a   of the error..*
f490: 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
f4a0: 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
f4b0: 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
f4c0: 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 5b  be UTF-8 if.** [
f4d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
f4e0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
f4f0: 5f 76 32 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  _v2()] is called
f500: 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
f510: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  f [sqlite3_open1
f520: 36 28 29 5d 20 69 73 20 75 73 65 64 2e 0a 2a 2a  6()] is used..**
f530: 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
f540: 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
f550: 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
f560: 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 20  ened, resources 
f570: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
f580: 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  th the [sqlite3*
f590: 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
f5a0: 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 70  be released by p
f5b0: 61 73 73 69 6e 67 20 69 74 20 74 6f 0a 2a 2a 20  assing it to.** 
f5c0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
f5d0: 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
f5e0: 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
f5f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
f600: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
f610: 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
f620: 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ike [sqlite3_ope
f630: 6e 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  n()] except that
f640: 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 74 77 6f  .** provides two
f650: 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
f660: 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
f670: 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 20 6f 76  ional control ov
f680: 65 72 20 74 68 65 0a 2a 2a 20 6e 65 77 20 64 61  er the.** new da
f690: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f6a0: 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61  n.  The flags pa
f6b0: 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 6f  rameter can be o
f6c0: 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  ne of:.**.** <ol
f6d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
f6e0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
f6f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
f700: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
f710: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  E].** <li>  [SQL
f720: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
f730: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
f740: 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f  EN_CREATE].** </
f750: 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ol>.**.** The fi
f760: 72 73 74 20 76 61 6c 75 65 20 6f 70 65 6e 73 20  rst value opens 
f770: 74 68 65 20 64 61 74 61 62 61 73 65 20 72 65 61  the database rea
f780: 64 2d 6f 6e 6c 79 2e 20 20 49 66 20 74 68 65 20  d-only.  If the 
f790: 64 61 74 61 62 61 73 65 20 64 6f 65 73 0a 2a 2a  database does.**
f7a0: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
f7b0: 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
f7c0: 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
f7d0: 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20  e second option 
f7e0: 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  opens.** the dat
f7f0: 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
f800: 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
f810: 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
f820: 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a  ading only if.**
f830: 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
f840: 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 2e  write protected.
f850: 20 20 49 6e 20 65 69 74 68 65 72 20 63 61 73 65    In either case
f860: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
f870: 73 74 20 61 6c 72 65 61 64 79 0a 2a 2a 20 65 78  st already.** ex
f880: 69 73 74 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  ist or an error 
f890: 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
f8a0: 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 20 6f  e third option o
f8b0: 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  pens the databas
f8c0: 65 0a 2a 2a 20 66 6f 72 20 72 65 61 64 69 6e 67  e.** for reading
f8d0: 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e 64   and writing and
f8e0: 20 63 72 65 61 74 65 73 20 69 74 20 69 66 20 69   creates it if i
f8f0: 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
f900: 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54 68 65  dy exist..** The
f910: 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73 20 69   third options i
f920: 73 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  s behavior that 
f930: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
f940: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
f950: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
f960: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
f970: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
f980: 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
f990: 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76  :", then an priv
f9a0: 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f 72 79  ate.** in-memory
f9b0: 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65   database is cre
f9c0: 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
f9d0: 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69  nection.  This i
f9e0: 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61 74 61  n-memory.** data
f9f0: 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
fa00: 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
fa10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
fa20: 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
fa30: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  .** version of S
fa40: 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61 6b 65  QLite might make
fa50: 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
fa60: 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
fa70: 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62 65 67  ames.** that beg
fa80: 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
fa90: 63 68 61 72 61 63 74 65 72 2e 20 20 49 74 20 69  character.  It i
faa0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
fab0: 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20 64 61  at .** when a da
fac0: 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
fad0: 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  really does begi
fae0: 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20 74 68  n with.** ":" th
faf0: 61 74 20 79 6f 75 20 70 72 65 66 69 78 20 74 68  at you prefix th
fb00: 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
fb10: 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b 65 20  a pathname like 
fb20: 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f 69 64  "./" to.** avoid
fb30: 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
fb40: 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  * If the filenam
fb50: 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
fb60: 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
fb70: 76 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a  vate temporary.*
fb80: 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
fb90: 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
fba0: 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74  ed.  This privat
fbb0: 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
fbc0: 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
fbd0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
fbe0: 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
fbf0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
fc00: 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
fc10: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
fc20: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
fc30: 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
fc40: 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
fc50: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
fc60: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
fc70: 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
fc80: 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74 65 72  system .** inter
fc90: 66 61 63 65 20 74 68 61 74 20 74 68 65 20 6e 65  face that the ne
fca0: 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
fcb0: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
fcc0: 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  .  If the.** fou
fcd0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
fce0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
fcf0: 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
fd00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a   [sqlite3_vfs].*
fd10: 2a 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  * object is used
fd20: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
fd30: 74 6f 20 77 69 6e 64 6f 77 73 20 75 73 65 72 73  to windows users
fd40: 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
fd50: 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
fd60: 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
fd70: 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69 74 65  nt.** of [sqlite
fd80: 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73  3_open()] and [s
fd90: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
fda0: 5d 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ] must be UTF-8,
fdb0: 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
fdc0: 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
fdd0: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
fde0: 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
fdf0: 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
fe00: 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
fe10: 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
fe20: 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
fe30: 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
fe40: 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  em into.** [sqli
fe50: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b  te3_open()] or [
fe60: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
fe70: 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
fe80: 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
fe90: 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
fea0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
feb0: 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
fec0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
fed0: 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
fee0: 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
fef0: 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
ff00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
ff10: 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
ff20: 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
ff30: 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
ff40: 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
ff50: 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
ff60: 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
ff70: 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
ff80: 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
ff90: 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
ffa0: 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
ffb0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
ffc0: 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
ffd0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
ffe0: 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
fff0: 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
10000 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
10010 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
10020 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
10030 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
10040 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
10050 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
10060 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
10070 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
10080 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
10090 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sages.**.** The 
100a0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
100b0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
100c0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a  rns the numeric.
100d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
100e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
100f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
10100 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
10110 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f  sult code].** fo
10120 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
10130 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
10140 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
10150 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b  ciated.** with [
10160 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20  sqlite3] handle 
10170 27 64 62 27 2e 20 20 49 66 20 61 20 70 72 69 6f  'db'.  If a prio
10180 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
10190 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73  d but the.** mos
101a0 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
101b0 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
101c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
101d0 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
101e0 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66  de().** is undef
101f0 69 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ined. .**.** The
10200 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
10210 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
10220 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
10230 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 61 75 67 65  English-langauge
10240 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
10250 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
10260 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
10270 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70 65  8 or UTF16 respe
10280 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
10290 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
102a0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
102b0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
102c0 6e 74 65 72 6e 61 6c 6c 79 2e 20 20 54 68 65 20  nternally.  The 
102d0 0a 2a 2a 20 73 74 72 69 6e 67 20 6d 61 79 20 62  .** string may b
102e0 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
102f0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 20   deallocated by 
10300 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
10310 20 74 6f 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e   to SQLite.** in
10320 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
10330 73 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 73 20 74  s..**.** Calls t
10340 6f 20 6d 61 6e 79 20 73 71 6c 69 74 65 33 5f 2a  o many sqlite3_*
10350 20 66 75 6e 63 74 69 6f 6e 73 20 73 65 74 20 74   functions set t
10360 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  he error code an
10370 64 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  d string returne
10380 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
10390 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71  _errcode()], [sq
103a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
103b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
103c0 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 28 6f 76  rmsg16()].** (ov
103d0 65 72 77 72 69 74 69 6e 67 20 74 68 65 20 70 72  erwriting the pr
103e0 65 76 69 6f 75 73 20 76 61 6c 75 65 73 29 2e 20  evious values). 
103f0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 73 20  Note that calls 
10400 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
10410 6f 64 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ode()],.** [sqli
10420 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61  te3_errmsg()], a
10430 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
10440 73 67 31 36 28 29 5d 20 74 68 65 6d 73 65 6c 76  sg16()] themselv
10450 65 73 20 64 6f 20 6e 6f 74 20 61 66 66 65 63 74  es do not affect
10460 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 73 20   the.** results 
10470 6f 66 20 66 75 74 75 72 65 20 69 6e 76 6f 63 61  of future invoca
10480 74 69 6f 6e 73 2e 20 20 43 61 6c 6c 73 20 74 6f  tions.  Calls to
10490 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68   API routines th
104a0 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e  at do not return
104b0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64  .** an error cod
104c0 65 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c  e (example: [sql
104d0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
104e0 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 63 68  )]) do not.** ch
104f0 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20 63  ange the error c
10500 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  ode returned by 
10510 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 49  this routine.  I
10520 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61  nterfaces that a
10530 72 65 0a 2a 2a 20 6e 6f 74 20 61 73 73 6f 63 69  re.** not associ
10540 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63  ated with a spec
10550 69 66 69 63 20 64 61 74 61 62 61 73 65 20 63 6f  ific database co
10560 6e 6e 65 63 74 69 6f 6e 20 28 65 78 61 6d 70 6c  nnection (exampl
10570 65 73 3a 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es:.** [sqlite3_
10580 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73  mprintf()] or [s
10590 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
105a0 61 72 65 64 5f 63 61 63 68 65 28 29 5d 20 64 6f  ared_cache()] do
105b0 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 74   not change.** t
105c0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 20  he return code. 
105d0 20 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e 67   .**.** Assuming
105e0 20 6e 6f 20 6f 74 68 65 72 20 69 6e 74 65 72 76   no other interv
105f0 65 6e 69 6e 67 20 73 71 6c 69 74 65 33 5f 2a 20  ening sqlite3_* 
10600 41 50 49 20 63 61 6c 6c 73 20 61 72 65 20 6d 61  API calls are ma
10610 64 65 2c 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  de, the error.**
10620 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62   code returned b
10630 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
10640 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
10650 74 68 20 74 68 65 20 73 61 6d 65 20 65 72 72 6f  th the same erro
10660 72 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  r as.** the stri
10670 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
10680 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
10690 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
106a0 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a  errmsg16()]..*/.
106b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
106c0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
106d0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
106e0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
106f0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
10700 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
10710 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
10720 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10730 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
10740 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 49 6e 73 74  bject.**.** Inst
10750 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10760 65 63 74 20 72 65 70 72 65 73 65 6e 74 20 73 69  ect represent si
10770 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
10780 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a 20 69 73  nts.  This.** is
10790 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
107a0 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
107b0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 20  statement" or a 
107c0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
107d0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
107e0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
107f0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20  tement"..** .** 
10800 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
10810 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
10820 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
10830 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
10840 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
10850 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
10860 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
10870 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
10880 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
10890 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
108a0 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
108b0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
108c0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b   using.**      [
108d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
108e0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
108f0 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d 2e 0a  _* interfaces]..
10900 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
10910 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
10920 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
10930 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
10940 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
10950 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
10960 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
10970 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
10980 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
10990 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
109a0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
109b0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
109c0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
109d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
109e0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
109f0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
10a00 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
10a10 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
10a20 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
10a30 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
10a40 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
10a50 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
10a60 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
10a70 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
10a80 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
10a90 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
10aa0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ment.**.** To ex
10ab0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
10ac0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
10ad0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
10ae0 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
10af0 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
10b00 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
10b10 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  tines. .**.** Th
10b20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10b30 20 22 64 62 22 20 69 73 20 61 6e 20 5b 73 71 6c   "db" is an [sql
10b40 69 74 65 33 20 7c 20 53 51 4c 69 74 65 20 64 61  ite3 | SQLite da
10b50 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d 20 0a  tabase handle] .
10b60 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
10b70 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
10b80 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
10b90 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
10ba0 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  _v2()].** or [sq
10bb0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
10bc0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
10bd0 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69  rgument "zSql" i
10be0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
10bf0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
10c00 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
10c10 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
10c20 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
10c30 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
10c40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
10c50 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
10c60 63 65 73 20 75 73 65 73 20 55 54 46 2d 38 20 61  ces uses UTF-8 a
10c70 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
10c80 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
10c90 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
10ca0 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
10cb0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42  .**.** If the nB
10cc0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
10cd0 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72  less.** than zer
10ce0 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
10cf0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66  read up to the f
10d00 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
10d10 61 74 6f 72 2e 20 20 49 66 0a 2a 2a 20 6e 42 79  ator.  If.** nBy
10d20 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
10d30 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
10d40 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
10d50 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20 72  r of .** bytes r
10d60 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
10d70 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
10d80 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
10d90 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
10da0 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
10db0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 63  e first '\000' c
10dc0 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20  haracter or .** 
10dd0 75 6e 74 69 6c 20 74 68 65 20 6e 42 79 74 65 2d  until the nByte-
10de0 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
10df0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
10e00 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73  **.** *pzTail is
10e10 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
10e20 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
10e30 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
10e40 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 53 51   the first.** SQ
10e50 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
10e60 53 71 6c 2e 20 20 54 68 69 73 20 72 6f 75 74 69  Sql.  This routi
10e70 6e 65 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73  ne only compiles
10e80 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
10e90 6d 65 6e 74 0a 2a 2a 20 69 6e 20 7a 53 71 6c 2c  ment.** in zSql,
10ea0 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
10eb0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
10ec0 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
10ed0 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a  ompiled..**.** *
10ee0 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
10ef0 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
10f00 70 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  piled .** [sqlit
10f10 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74  e3_stmt | SQL st
10f20 61 74 65 6d 65 6e 74 20 73 74 72 75 63 74 75 72  atement structur
10f30 65 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  e] that can be.*
10f40 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
10f50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
10f60 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72 65 20  ].  Or if there 
10f70 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
10f80 53 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a 20 73  Stmt may be.** s
10f90 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20  et to NULL.  If 
10fa0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
10fb0 6f 6e 74 61 69 6e 65 64 20 6e 6f 20 53 51 4c 20  ontained no SQL 
10fc0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
10fd0 20 61 6e 64 0a 2a 2a 20 65 6d 70 74 79 20 73 74   and.** empty st
10fe0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
10ff0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
11000 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20  is set to NULL. 
11010 20 54 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   The calling.** 
11020 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
11030 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
11040 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
11050 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
11060 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
11070 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
11080 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
11090 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
110a0 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
110b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
110c0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
110d0 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49  ise an .** [SQLI
110e0 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72  TE_ERROR | error
110f0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
11100 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
11110 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
11120 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
11130 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
11140 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
11150 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
11160 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
11170 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
11180 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
11190 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
111a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
111b0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
111c0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
111d0 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20  aged..** In the 
111e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
111f0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
11200 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
11210 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
11220 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
11230 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
11240 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a   a copy of the .
11250 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
11260 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
11270 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
11280 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
11290 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20   to.** behave a 
112a0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
112b0 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  wo ways:.**.** <
112c0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49  ol>.** <li>.** I
112d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
112e0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
112f0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
11300 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
11310 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
11320 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
11330 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
11340 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
11350 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
11360 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
11370 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
11380 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20  n it again.  If 
11390 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
113a0 68 61 6e 67 65 64 20 69 6e 20 61 20 77 61 79 0a  hanged in a way.
113b0 2a 2a 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ** that makes th
113c0 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
113d0 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
113e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
113f0 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
11400 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
11410 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
11420 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
11430 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  ior, [SQLITE_SCH
11440 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61  EMA] is.** now a
11450 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
11460 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
11470 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
11480 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
11490 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
114a0 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
114b0 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
114c0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
114d0 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 61  e text of the pa
114e0 72 73 69 6e 67 0a 2a 2a 20 65 72 72 6f 72 20 74  rsing.** error t
114f0 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
11500 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
11510 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c  ] return..** </l
11520 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
11530 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f   When an error o
11540 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69  ccurs, .** [sqli
11550 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
11560 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
11570 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20  he detailed .** 
11580 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
11590 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
115a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
115b0 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
115c0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
115d0 73 75 63 68 20 61 73 20 64 69 72 65 63 74 6c 79  such as directly
115e0 2e 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 79 20  ..** The legacy 
115f0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
11600 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  t [sqlite3_step(
11610 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
11620 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a  turn a generic.*
11630 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
11640 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6e 64   result code and
11650 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20   you would have 
11660 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
11670 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
11680 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e  ite3_reset()] in
11690 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
116a0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
116b0 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
116c0 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  em..** With the 
116d0 22 76 32 22 20 70 72 65 70 61 72 65 20 69 6e 74  "v2" prepare int
116e0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
116f0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
11700 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 0a  or the error is.
11710 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  ** returned imme
11720 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
11730 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e  >.** </ol>.*/.in
11740 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
11750 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
11760 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
11770 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
11780 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
11790 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
117a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
117b0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
117c0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
117d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
117e0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
117f0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
11800 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
11810 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
11820 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
11830 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
11840 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
11850 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
11860 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
11870 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
11880 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
11890 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
118a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
118b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
118c0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
118d0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
118e0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
118f0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
11900 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
11910 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
11920 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
11930 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
11940 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
11950 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
11960 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
11970 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
11980 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
11990 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
119a0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
119b0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
119c0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
119d0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
119e0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
119f0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
11a00 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
11a10 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
11a20 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
11a30 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
11a40 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
11a50 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
11a60 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
11a70 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
11a80 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
11a90 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
11aa0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
11ab0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
11ac0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
11ad0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
11ae0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
11af0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
11b00 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
11b10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
11b20 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
11b30 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
11b40 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
11b50 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
11b60 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
11b70 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
11b80 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
11b90 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
11ba0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
11bb0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
11bc0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
11bd0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
11be0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
11bf0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
11c00 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
11c10 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
11c20 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
11c30 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
11c40 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
11c50 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
11c60 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69 63 61  I3REF:  Dynamica
11c70 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
11c80 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 53 51 4c  Object.**.** SQL
11c90 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
11ca0 20 74 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20   typing for the 
11cb0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
11cc0 2e 20 20 56 61 6c 75 65 73 20 63 61 6e 20 0a 2a  .  Values can .*
11cd0 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  * be integers, f
11ce0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
11cf0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
11d00 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 20 20  LOBs, or NULL.  
11d10 57 68 65 6e 0a 2a 2a 20 70 61 73 73 69 6e 67 20  When.** passing 
11d20 61 72 6f 75 6e 64 20 76 61 6c 75 65 73 20 69 6e  around values in
11d30 74 65 72 6e 61 6c 6c 79 2c 20 65 61 63 68 20 76  ternally, each v
11d40 61 6c 75 65 20 69 73 20 72 65 70 72 65 73 65 6e  alue is represen
11d50 74 65 64 20 61 73 0a 2a 2a 20 61 6e 20 69 6e 73  ted as.** an ins
11d60 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
11d70 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
11d80 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
11d90 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
11da0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
11db0 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75  API3REF:  SQL Fu
11dc0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
11dd0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
11de0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
11df0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
11e00 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
11e10 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
11e20 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
11e30 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20  ect.  A pointer 
11e40 74 6f 20 73 75 63 68 20 61 6e 20 6f 62 6a 65 63  to such an objec
11e50 74 20 69 73 20 74 68 65 0a 2a 2a 20 66 69 72 73  t is the.** firs
11e60 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 75  t parameter to u
11e70 73 65 72 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ser-defined SQL 
11e80 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79  functions..*/.ty
11e90 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
11ea0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
11eb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
11ec0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
11ed0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
11ee0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
11ef0 6d 65 6e 74 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  ments.**.** In t
11f00 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69  he SQL strings i
11f10 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
11f20 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
11f30 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
11f40 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
11f50 6c 69 74 65 72 61 6c 73 20 63 61 6e 20 62 65 20  literals can be 
11f60 72 65 70 6c 61 63 65 20 62 79 20 61 20 70 61 72  replace by a par
11f70 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66  ameter in one of
11f80 20 74 68 65 73 65 0a 2a 2a 20 66 6f 72 6d 73 3a   these.** forms:
11f90 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
11fa0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
11fb0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 41  ?NNN.** <li>  :A
11fc0 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41 41 41  AA.** <li>  @AAA
11fd0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
11fe0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
11ff0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66   the parameter f
12000 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  orms shown above
12010 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67   NNN is an integ
12020 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 41  er literal,.** A
12030 41 41 20 69 73 20 61 6e 20 61 6c 70 68 61 6e 75  AA is an alphanu
12040 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
12050 20 61 6e 64 20 56 56 56 20 69 73 20 61 20 76 61   and VVV is a va
12060 72 69 61 62 6c 65 20 6e 61 6d 65 20 61 63 63 6f  riable name acco
12070 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  rding.** to the 
12080 73 79 6e 74 61 78 20 72 75 6c 65 73 20 6f 66 20  syntax rules of 
12090 74 68 65 20 54 43 4c 20 70 72 6f 67 72 61 6d 6d  the TCL programm
120a0 69 6e 67 20 6c 61 6e 67 75 61 67 65 2e 0a 2a 2a  ing language..**
120b0 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74   The values of t
120c0 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20  hese parameters 
120d0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
120e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
120f0 65 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  es").** can be s
12100 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
12110 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
12120 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
12130 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ere..**.** The f
12140 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
12150 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
12160 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
12170 6c 77 61 79 73 20 69 73 20 61 20 70 6f 69 6e 74  lways is a point
12180 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
12190 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
121a0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
121b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
121c0 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 69 74  e_v2()] or.** it
121d0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 54 68 65  s variants.  The
121e0 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
121f0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
12200 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
12210 72 20 74 6f 20 62 65 20 73 65 74 2e 20 20 54 68  r to be set.  Th
12220 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12230 72 20 68 61 73 0a 2a 2a 20 61 6e 20 69 6e 64 65  r has.** an inde
12240 78 20 6f 66 20 31 2e 20 57 68 65 6e 20 74 68 65  x of 1. When the
12250 20 73 61 6d 65 20 6e 61 6d 65 64 20 70 61 72 61   same named para
12260 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
12270 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
12280 63 6f 6e 64 0a 2a 2a 20 61 6e 64 20 73 75 62 73  cond.** and subs
12290 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
122a0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
122b0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
122c0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
122d0 65 2e 20 20 54 68 65 20 69 6e 64 65 78 20 66 6f  e.  The index fo
122e0 72 0a 2a 2a 20 6e 61 6d 65 64 20 70 61 72 61 6d  r.** named param
122f0 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
12300 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
12310 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
12320 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
12330 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
12340 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 20 66  ed.  The index f
12350 6f 72 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 70 61 72  or "?NNN".** par
12360 61 6d 65 74 65 73 20 69 73 20 74 68 65 20 76 61  ametes is the va
12370 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54  lue of NNN..** T
12380 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
12390 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
123a0 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  nd the compile-t
123b0 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ime.** parameter
123c0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
123d0 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66  ABLE_NUMBER (def
123e0 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
123f0 2e 0a 2a 2a 20 53 65 65 20 3c 61 20 68 72 65 66  ..** See <a href
12400 3d 22 6c 69 6d 69 74 73 2e 68 74 6d 6c 22 3e 6c  ="limits.html">l
12410 69 6d 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e 20 66  imits.html</a> f
12420 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
12430 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
12440 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
12450 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
12460 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
12470 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
12480 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f 75   In those.** rou
12490 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
124a0 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
124b0 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
124c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
124d0 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70 61  tes.** in the pa
124e0 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
124f0 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
12500 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
12510 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 0a 2a  f bytes in the.*
12520 2a 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  * string, not th
12530 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
12540 61 63 74 65 72 73 2e 20 20 54 68 65 20 6e 75 6d  acters.  The num
12550 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
12560 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
12570 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
12580 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 20  ator at the end 
12590 6f 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49  of strings..** I
125a0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
125b0 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
125c0 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  ve, the length o
125d0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
125e0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
125f0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
12600 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
12610 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  or..**.** The fi
12620 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
12630 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
12640 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
12650 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
12660 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
12670 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
12680 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
12690 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
126a0 4f 42 20 6f 72 0a 2a 2a 20 74 65 78 74 20 61 66  OB or.** text af
126b0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
126c0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
126d0 20 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61    If the fifth a
126e0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
126f0 2a 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  * special value 
12700 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
12710 20 74 68 65 6e 20 74 68 65 20 6c 69 62 72 61 72   then the librar
12720 79 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  y assumes that t
12730 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  he information.*
12740 2a 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  * is in static, 
12750 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
12760 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
12770 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 20 20  d to be freed.  
12780 49 66 20 74 68 65 0a 2a 2a 20 66 69 66 74 68 20  If the.** fifth 
12790 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
127a0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
127b0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 20  RANSIENT], then 
127c0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
127d0 0a 2a 2a 20 6f 77 6e 20 70 72 69 76 61 74 65 20  .** own private 
127e0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
127f0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
12800 66 6f 72 65 20 74 68 65 20 73 71 6c 69 74 65 33  fore the sqlite3
12810 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 72 6f 75  _bind_*().** rou
12820 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
12830 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12840 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
12850 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
12860 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 6e  BLOB of length n
12870 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
12880 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  ed with zeros.  
12890 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
128a0 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
128b0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
128c0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
128d0 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68  hold it size) wh
128e0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
128f0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
12900 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
12910 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
12920 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66   place-holders f
12930 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
12940 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
12950 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
12960 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c   .** [sqlite3_bl
12970 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
12980 65 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  ent BLOB I/O] ro
12990 75 74 69 6e 65 73 2e 20 20 41 20 6e 65 67 61 74  utines.  A negat
129a0 69 76 65 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72  ive.** value for
129b0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
129c0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
129d0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
129e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
129f0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
12a00 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
12a10 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  after.** [sqlite
12a20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
12a30 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74  (and its variant
12a40 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  s) or [sqlite3_r
12a50 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62  eset()] and.** b
12a60 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
12a70 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69  tep()]..** Bindi
12a80 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
12a90 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
12aa0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
12ab0 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64  tine..** Unbound
12ac0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
12ad0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
12ae0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ULL..**.** These
12af0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
12b00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
12b10 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72  success or an er
12b20 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61  ror code if.** a
12b30 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
12b40 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e  ng.  [SQLITE_RAN
12b50 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
12b60 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
12b70 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
12b80 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c   of range.  [SQL
12b90 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
12ba0 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
12bb0 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49   fails..** [SQLI
12bc0 54 45 5f 4d 49 53 55 53 45 5d 20 69 73 20 72 65  TE_MISUSE] is re
12bd0 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20  turned if these 
12be0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
12bf0 6c 65 64 20 6f 6e 20 61 20 76 69 72 74 75 61 6c  led on a virtual
12c00 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 74 68 61 74  .** machine that
12c10 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74   is the wrong st
12c20 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73  ate or which has
12c30 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69   already been fi
12c40 6e 61 6c 69 7a 65 64 2e 0a 2a 2f 0a 69 6e 74 20  nalized..*/.int 
12c50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
12c60 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
12c70 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
12c80 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
12c90 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
12ca0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
12cb0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
12cc0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
12cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
12ce0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
12cf0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
12d00 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
12d10 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
12d20 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
12d30 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
12d40 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
12d50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
12d60 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
12d70 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
12d80 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
12d90 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
12da0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
12db0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
12dc0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
12dd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
12de0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
12df0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
12e00 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
12e10 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
12e20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
12e30 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
12e40 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
12e50 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
12e60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
12e70 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
12e80 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
12e90 65 72 20 4f 66 20 48 6f 73 74 20 50 61 72 61 6d  er Of Host Param
12ea0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 52 65 74 75  eters.**.** Retu
12eb0 72 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 68  rn the largest h
12ec0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 6e  ost parameter in
12ed0 64 65 78 20 69 6e 20 74 68 65 20 70 72 65 63 6f  dex in the preco
12ee0 6d 70 69 6c 65 64 20 73 74 61 74 65 6d 65 6e 74  mpiled statement
12ef0 20 67 69 76 65 6e 0a 2a 2a 20 61 73 20 74 68 65   given.** as the
12f00 20 61 72 67 75 6d 65 6e 74 2e 20 20 57 68 65 6e   argument.  When
12f10 20 74 68 65 20 68 6f 73 74 20 70 61 72 61 6d 65   the host parame
12f20 74 65 72 73 20 61 72 65 20 6f 66 20 74 68 65 20  ters are of the 
12f30 66 6f 72 6d 73 20 6c 69 6b 65 20 22 3a 41 41 41  forms like ":AAA
12f40 22 0a 2a 2a 20 6f 72 20 22 3f 22 2c 20 74 68 65  ".** or "?", the
12f50 6e 20 74 68 65 79 20 61 72 65 20 61 73 73 69 67  n they are assig
12f60 6e 65 64 20 73 65 71 75 65 6e 74 69 61 6c 20 69  ned sequential i
12f70 6e 63 72 65 61 73 69 6e 67 20 6e 75 6d 62 65 72  ncreasing number
12f80 73 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 77  s beginning.** w
12f90 69 74 68 20 6f 6e 65 2c 20 73 6f 20 74 68 65 20  ith one, so the 
12fa0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
12fb0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
12fc0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 48 6f 77  parameters.  How
12fd0 65 76 65 72 0a 2a 2a 20 69 66 20 74 68 65 20 73  ever.** if the s
12fe0 61 6d 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74  ame host paramet
12ff0 65 72 20 6e 61 6d 65 20 69 73 20 75 73 65 64 20  er name is used 
13000 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 2c 20  multiple times, 
13010 65 61 63 68 20 6f 63 63 75 72 72 61 6e 63 65 0a  each occurrance.
13020 2a 2a 20 69 73 20 67 69 76 65 6e 20 74 68 65 20  ** is given the 
13030 73 61 6d 65 20 6e 75 6d 62 65 72 2c 20 73 6f 20  same number, so 
13040 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
13050 65 64 20 69 6e 20 74 68 61 74 20 63 61 73 65 20  ed in that case 
13060 69 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  is the number.**
13070 20 6f 66 20 75 6e 69 71 75 65 20 68 6f 73 74 20   of unique host 
13080 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 2e  parameter names.
13090 20 20 49 66 20 68 6f 73 74 20 70 61 72 61 6d 65    If host parame
130a0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
130b0 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 61 72 65 20 75   "?NNN".** are u
130c0 73 65 64 20 28 77 68 65 72 65 20 4e 4e 4e 20 69  sed (where NNN i
130d0 73 20 61 6e 20 69 6e 74 65 67 65 72 29 20 74 68  s an integer) th
130e0 65 6e 20 74 68 65 72 65 20 6d 69 67 68 74 20 62  en there might b
130f0 65 20 67 61 70 73 20 69 6e 20 74 68 65 0a 2a 2a  e gaps in the.**
13100 20 6e 75 6d 62 65 72 69 6e 67 20 61 6e 64 20 74   numbering and t
13110 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
13120 64 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  d by this interf
13130 61 63 65 20 69 73 20 74 68 65 20 69 6e 64 65 78  ace is the index
13140 20 6f 66 20 74 68 65 0a 2a 2a 20 68 6f 73 74 20   of the.** host 
13150 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 74  parameter with t
13160 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78  he largest index
13170 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   value..**.** Th
13180 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
13190 6d 65 6e 74 20 6d 75 73 74 20 6e 6f 74 20 62 65  ment must not be
131a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
131b0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 0a  ze | finalized].
131c0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 69 73  ** prior to this
131d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 6e   routine returnn
131e0 69 6e 67 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ing.  Otherwise 
131f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
13200 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 61 6e 64  undefined.** and
13210 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
13220 72 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  rable..*/.int sq
13230 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
13240 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
13250 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
13260 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
13270 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
13280 65 74 65 72 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eter.**.** This 
13290 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
132a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
132b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74   name of the n-t
132c0 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 61  h parameter in a
132d0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
132e0 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
132f0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 48 6f 73  atement]..** Hos
13300 74 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  t parameters of 
13310 74 68 65 20 66 6f 72 6d 20 22 3a 41 41 41 22 20  the form ":AAA" 
13320 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 56  or "@AAA" or "$V
13330 56 56 22 20 68 61 76 65 20 61 20 6e 61 6d 65 0a  VV" have a name.
13340 2a 2a 20 77 68 69 63 68 20 69 73 20 74 68 65 20  ** which is the 
13350 73 74 72 69 6e 67 20 22 3a 41 41 41 22 20 6f 72  string ":AAA" or
13360 20 22 40 41 41 41 22 20 6f 72 20 22 24 56 56 56   "@AAA" or "$VVV
13370 22 2e 20 20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ".  .** In other
13380 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
13390 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
133a0 72 20 22 40 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "@".** is incl
133b0 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
133c0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72  the name..** Par
133d0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
133e0 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e  orm "?" or "?NNN
133f0 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a  " have no name..
13400 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
13410 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20  bound parameter 
13420 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
13430 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
13440 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69  If the value n i
13450 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
13460 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61  r if the n-th pa
13470 72 61 6d 65 74 65 72 20 69 73 20 6e 61 6d 65 6c  rameter is namel
13480 65 73 73 2c 0a 2a 2a 20 74 68 65 6e 20 4e 55 4c  ess,.** then NUL
13490 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
134a0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
134b0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 69 6e  ing is always in
134c0 20 74 68 65 0a 2a 2a 20 55 54 46 2d 38 20 65 6e   the.** UTF-8 en
134d0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
134e0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
134f0 65 72 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c  er was originall
13500 79 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 61  y specified.** a
13510 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
13520 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
13530 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
13540 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
13550 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
13560 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
13570 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
13580 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
13590 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
135a0 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
135b0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
135c0 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69  n Name.**.** Thi
135d0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
135e0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  s the index of a
135f0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
13600 77 69 74 68 20 74 68 65 20 67 69 76 65 6e 20 6e  with the given n
13610 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ame..** The name
13620 20 6d 75 73 74 20 6d 61 74 63 68 20 65 78 61 63   must match exac
13630 74 6c 79 2e 20 20 49 66 20 6e 6f 20 70 61 72 61  tly.  If no para
13640 6d 65 74 65 72 20 77 69 74 68 20 74 68 65 20 67  meter with the g
13650 69 76 65 6e 20 6e 61 6d 65 20 69 73 20 0a 2a 2a  iven name is .**
13660 20 66 6f 75 6e 64 2c 20 72 65 74 75 72 6e 20 30   found, return 0
13670 2e 20 20 50 61 72 61 6d 65 74 65 72 20 6e 61 6d  .  Parameter nam
13680 65 73 20 6d 75 73 74 20 62 65 20 55 54 46 38 2e  es must be UTF8.
13690 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
136a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
136b0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
136c0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
136d0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
136e0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
136f0 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
13700 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
13710 65 6e 74 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  ent.**.** Contra
13720 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
13730 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
13740 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
13750 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74  oes not.** reset
13760 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
13770 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
13780 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 73 71  gs] on a .** [sq
13790 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
137a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
137b0 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  .  Use this rout
137c0 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20  ine to.** reset 
137d0 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
137e0 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
137f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
13800 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
13810 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
13820 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
13830 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
13840 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
13850 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e  .** Return the n
13860 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
13870 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
13880 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
13890 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
138a0 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20  stmt | compiled 
138b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  SQL statement]. 
138c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
138d0 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74  urns 0.** if pSt
138e0 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61  mt is an SQL sta
138f0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
13900 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
13910 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c   (for .** exampl
13920 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2f  e an UPDATE)..*/
13930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
13940 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
13950 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
13960 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13970 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
13980 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
13990 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
139a0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
139b0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
139c0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
139d0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
139e0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
139f0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ECT statement.  
13a00 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
13a10 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
13a20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
13a30 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54   pointer to a UT
13a40 46 38 20 73 74 72 69 6e 67 20 61 6e 64 20 73 71  F8 string and sq
13a50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
13a60 65 31 36 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  e16().** returns
13a70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
13a80 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54  UTF16 string.  T
13a90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
13aa0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 73 71  er is the.** [sq
13ab0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
13ac0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
13ad0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
13ae0 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74   the SELECT stat
13af0 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65  ement..** The se
13b00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
13b10 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d  s the column num
13b20 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d  ber.  The left-m
13b30 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a  ost column is.**
13b40 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
13b50 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
13b60 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
13b70 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
13b80 65 72 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  er the .** [sqli
13b90 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61  te3_stmt | prepa
13ba0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
13bb0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
13bc0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
13bd0 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  ()].** or until 
13be0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71  the next call sq
13bf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
13c00 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
13c10 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a  olumn_name16().*
13c20 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  * on the same co
13c30 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73  lumn..**.** If s
13c40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
13c50 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
13c60 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
13c70 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
13c80 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
13c90 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
13ca0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
13cb0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
13cc0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
13cd0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 63  s returned..*/.c
13ce0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
13cf0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
13d00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
13d10 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
13d20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
13d30 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
13d40 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
13d50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13d60 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
13d70 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
13d80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
13d90 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
13da0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
13db0 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f  ne what column o
13dc0 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20  f what.** table 
13dd0 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73  in which databas
13de0 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20  e a result of a 
13df0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
13e00 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20   comes from..** 
13e10 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
13e20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
13e30 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
13e40 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
13e50 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 38 20  * either a UTF8 
13e60 6f 72 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e  or UTF16 string.
13e70 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f    The _database_
13e80 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
13e90 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
13ea0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
13eb0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
13ec0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
13ed0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
13ee0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
13ef0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
13f00 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65   name..** The re
13f10 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
13f20 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20   valid until.** 
13f30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
13f40 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
13f50 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
13f60 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  oyed using.** [s
13f70 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
13f80 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
13f90 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
13fa0 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
13fb0 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
13fc0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
13fd0 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20  **.** The names 
13fe0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
13ff0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
14000 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
14010 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
14020 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
14030 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
14040 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
14050 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c  e following call
14060 73 20 69 73 20 61 20 0a 2a 2a 20 5b 73 71 6c 69  s is a .** [sqli
14070 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69  te3_stmt | compi
14080 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
14090 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  t]..** These fun
140a0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
140b0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
140c0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
140d0 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74  eturned by .** t
140e0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
140f0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
14100 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
14110 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ument..**.** If 
14120 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
14130 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
14140 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
14150 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20  xpression.** or 
14160 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
14170 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
14180 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
14190 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a  these functions.
141a0 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20  ** return NULL. 
141b0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
141c0 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e  return the .** n
141d0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
141e0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
141f0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  ble and column t
14200 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
14210 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  .** column was e
14220 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
14230 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c  *.** As with all
14240 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
14250 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69  Is, those postfi
14260 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65  xed with "16" re
14270 74 75 72 6e 20 55 54 46 2d 31 36 0a 2a 2a 20 65  turn UTF-16.** e
14280 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20  ncoded strings, 
14290 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
142a0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
142b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50  ..**.** These AP
142c0 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
142d0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
142e0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
142f0 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
14300 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
14310 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65  UMN_METADATA pre
14320 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
14330 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
14340 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
14350 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
14360 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
14370 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
14380 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
14390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
143a0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
143b0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
143c0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
143d0 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
143e0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
143f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
14400 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
14410 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
14420 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
14430 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
14440 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
14450 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
14460 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
14470 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
14480 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
14490 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
144a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
144b0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
144c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
144d0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
144e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
144f0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
14500 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
14510 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
14520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
14530 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
14540 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
14550 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
14560 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
14570 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
14580 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  t.**.** The firs
14590 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
145a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
145b0 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74   compiled SQL st
145c0 61 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66  atement]. .** If
145d0 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
145e0 69 73 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  is a SELECT stat
145f0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
14600 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
14610 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
14620 75 6c 74 20 73 65 74 20 20 6f 66 20 74 68 61 74  ult set  of that
14630 20 53 45 4c 45 43 54 20 69 73 20 61 20 74 61 62   SELECT is a tab
14640 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
14650 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
14660 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
14670 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
14680 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
14690 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
146a0 74 75 72 6e 65 64 2e 20 49 66 20 74 68 65 20 4e  turned. If the N
146b0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
146c0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
146d0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
146e0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
146f0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
14700 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
14710 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
14720 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
14730 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 46 6f  TF-8 encoded. Fo
14740 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 0a 2a 2a  r example, in.**
14750 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
14760 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
14770 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
14780 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41  ARIANT);.**.** A
14790 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
147a0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
147b0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
147c0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
147d0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e  M t1;.**.** Then
147e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
147f0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
14800 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
14810 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  for the second.*
14820 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  * result column 
14830 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
14840 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
14850 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
14860 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29  column.** (i==0)
14870 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ..**.** SQLite u
14880 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
14890 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f  time typing.  So
148a0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
148b0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
148c0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
148d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
148e0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
148f0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
14900 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
14910 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
14920 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
14930 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
14940 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
14950 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
14960 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
14970 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73  tic.  Type.** is
14980 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
14990 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
149a0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
149b0 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
149c0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
149d0 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
149e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
149f0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
14a00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2c  (sqlite3_stmt *,
14a10 20 69 6e 74 20 69 29 3b 0a 63 6f 6e 73 74 20 76   int i);.const v
14a20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
14a30 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
14a40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
14a50 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33  );../* .** CAPI3
14a60 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65 20 41  REF:  Evaluate A
14a70 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
14a80 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e 20 5b  **.** After an [
14a90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53  sqlite3_stmt | S
14aa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  QL statement] ha
14ab0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
14ac0 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74  with a call.** t
14ad0 6f 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  o either [sqlite
14ae0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
14af0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
14b00 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
14b10 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  o one of.** the 
14b20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
14b30 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
14b40 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
14b50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a  3_prepare16()],.
14b60 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 66 75 6e  ** then this fun
14b70 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 63 61  ction must be ca
14b80 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
14b90 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
14ba0 74 65 20 74 68 65 20 0a 2a 2a 20 73 74 61 74 65  te the .** state
14bb0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
14bc0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
14bd0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
14be0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
14bf0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
14c00 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
14c10 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
14c20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
14c30 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
14c40 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
14c50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
14c60 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
14c70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
14c80 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
14c90 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
14ca0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14cb0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
14cc0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
14cd0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
14ce0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
14cf0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
14d00 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
14d10 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
14d20 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
14d30 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
14d40 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
14d50 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ed..**.** In the
14d60 20 6c 61 67 61 63 79 20 69 6e 74 65 72 66 61 63   lagacy interfac
14d70 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
14d80 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
14d90 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
14da0 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  , .** [SQLITE_DO
14db0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
14dc0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
14dd0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
14de0 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  SUSE]..** With t
14df0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
14e00 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
14e10 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  her [SQLITE_OK |
14e20 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a   result code].**
14e30 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
14e40 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
14e50 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d  d result code] m
14e60 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
14e70 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a   as.** well..**.
14e80 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
14e90 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
14ea0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
14eb0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
14ec0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
14ed0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
14ee0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
14ef0 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  ob.  If the stat
14f00 65 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49  ement is a COMMI
14f10 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  T.** or occurs o
14f20 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
14f30 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
14f40 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
14f50 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
14f60 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
14f70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
14f80 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63   a COMMIT and oc
14f90 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a  curs within a.**
14fa0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
14fb0 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
14fc0 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
14fd0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
14fe0 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
14ff0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ing..**.** [SQLI
15000 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
15010 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
15020 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
15030 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
15040 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
15050 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
15060 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
15070 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
15080 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
15090 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
150a0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
150b0 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
150c0 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
150d0 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
150e0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
150f0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
15100 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
15110 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
15120 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
15130 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  hen .** [SQLITE_
15140 52 4f 57 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROW] is returned
15150 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
15160 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
15170 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f  ready.** for pro
15180 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 20 63  cessing by the c
15190 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
151a0 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
151b0 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  d using.** the [
151c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
151d0 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65  nt | column acce
151e0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
151f0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
15200 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
15210 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
15220 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
15230 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54  a..** .** [SQLIT
15240 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
15250 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
15260 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
15270 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
15280 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
15290 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
152a0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
152b0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
152c0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
152d0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
152e0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
152f0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
15300 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
15310 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
15320 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
15330 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
15340 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a   code (example:.
15350 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
15360 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
15370 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
15380 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
15390 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
153a0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
153b0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
153c0 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
153d0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
153e0 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
153f0 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
15400 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
15410 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
15420 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
15430 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
15440 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
15450 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
15460 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
15470 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
15480 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
15490 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
154a0 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
154b0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
154c0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
154d0 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
154e0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
154f0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
15500 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
15510 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
15520 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
15530 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  d .** previously
15540 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
15550 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
15560 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
15570 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
15580 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
15590 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
155a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
155b0 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
155c0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
155d0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
155e0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
155f0 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
15600 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
15610 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63  .** In the legac
15620 79 20 69 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a  y interface, .**
15630 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
15640 70 28 29 20 41 50 49 20 61 6c 77 61 79 73 20 72  p() API always r
15650 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
15660 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20   error code,.** 
15670 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
15680 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72  following any er
15690 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
156a0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
156b0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
156c0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
156d0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  all [sqlite3_res
156e0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
156f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
15700 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
15710 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70 65  d one of the spe
15720 63 69 66 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45  cific.** [SQLITE
15730 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20  _ERROR | result 
15740 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
15750 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
15760 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
15770 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
15780 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
15790 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
157a0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
157b0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
157c0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
157d0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
157e0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
157f0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
15800 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
15810 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
15820 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
15830 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
15840 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
15850 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15860 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
15870 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
15880 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65  hen the .** more
15890 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49 54   specific [SQLIT
158a0 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74  E_ERROR | result
158b0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
158c0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
158d0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
158e0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
158f0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
15900 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
15910 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
15920 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
15930 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
15940 50 49 33 52 45 46 3a 0a 2a 2a 0a 2a 2a 20 52 65  PI3REF:.**.** Re
15950 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
15960 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  of values in the
15970 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
15980 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  the result set..
15990 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 63 61  **.** After a ca
159a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
159b0 74 65 70 28 29 5d 20 74 68 61 74 20 72 65 74 75  tep()] that retu
159c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  rns [SQLITE_ROW]
159d0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  , this routine.*
159e0 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  * will return th
159f0 65 20 73 61 6d 65 20 76 61 6c 75 65 20 61 73 20  e same value as 
15a00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
15a10 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 20 66 75 6e  umn_count()] fun
15a20 63 74 69 6f 6e 2e 0a 2a 2a 20 41 66 74 65 72 20  ction..** After 
15a30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
15a40 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e   has returned an
15a50 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
15a60 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f  [SQLITE_BUSY], o
15a70 72 0a 2a 2a 20 61 20 5b 53 51 4c 49 54 45 5f 45  r.** a [SQLITE_E
15a80 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64  RROR | error cod
15a90 65 5d 2c 20 6f 72 20 62 65 66 6f 72 65 20 5b 73  e], or before [s
15aa0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
15ab0 61 73 20 62 65 65 6e 20 0a 2a 2a 20 63 61 6c 6c  as been .** call
15ac0 65 64 20 6f 6e 20 74 68 65 20 5b 73 71 6c 69 74  ed on the [sqlit
15ad0 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
15ae0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f  ed statement] fo
15af0 72 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  r the first time
15b00 2c 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  ,.** this routin
15b10 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  e returns zero..
15b20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
15b30 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
15b40 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
15b50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15b60 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
15b70 61 74 79 70 65 73 0a 2a 2a 0a 2a 2a 20 45 76 65  atypes.**.** Eve
15b80 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
15b90 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
15ba0 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
15bb0 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
15bc0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
15bd0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
15be0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
15bf0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
15c00 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
15c10 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
15c20 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
15c30 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   NULL.** </ul>.*
15c40 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
15c50 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
15c60 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
15c70 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
15c80 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
15c90 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
15ca0 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
15cb0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
15cc0 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
15cd0 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
15ce0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
15cf0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
15d00 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
15d10 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
15d20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
15d30 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
15d40 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f 74  SQLITE3_TEXT not
15d50 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
15d60 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
15d70 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
15d80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
15d90 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
15da0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
15db0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
15dc0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
15dd0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
15de0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
15df0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
15e00 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
15e10 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
15e20 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
15e30 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
15e40 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20 56  I3REF: Results V
15e50 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
15e60 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ry.**.** These r
15e70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
15e80 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
15e90 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  .** a single col
15ea0 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
15eb0 6e 74 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  nt result row of
15ec0 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76   a query.  In ev
15ed0 65 72 79 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  ery.** case the 
15ee0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
15ef0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
15f00 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
15f10 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61 74 65  stmt | SQL state
15f20 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
15f30 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64  ing.** evaluated
15f40 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
15f50 74 6d 74 2a 5d 20 74 68 61 74 20 77 61 73 20 72  tmt*] that was r
15f60 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  eturned from .**
15f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15f80 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
15f90 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  f its variants) 
15fa0 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  and.** the secon
15fb0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
15fc0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
15fd0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
15fe0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20  information .** 
15ff0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
16000 65 64 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f  ed.  The left-mo
16010 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
16020 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68   result set.** h
16030 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30  as an index of 0
16040 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
16050 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
16060 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
16070 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
16080 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
16090 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65   the column inde
160a0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
160b0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
160c0 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20   undefined. .** 
160d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
160e0 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
160f0 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
16100 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
16110 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
16120 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
16130 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
16140 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
16150 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
16160 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
16170 69 7a 65 28 29 5d 20 68 61 73 20 62 65 65 6e 20  ize()] has been 
16180 63 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 6c  call subsequentl
16190 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
161a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
161b0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
161c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
161d0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
161e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
161f0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
16200 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
16210 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
16220 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
16230 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
16240 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
16250 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
16260 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
16270 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
16280 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
16290 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
162a0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
162b0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
162c0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
162d0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
162e0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
162f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
16300 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a  undefined.  .**.
16310 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
16320 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
16330 74 69 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tine returns .**
16340 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
16350 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
16360 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
16370 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
16380 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
16390 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e  umn.  The return
163a0 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
163b0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
163c0 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
163d0 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
163e0 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
163f0 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
16400 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
16410 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
16420 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
16430 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
16440 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
16450 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
16460 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
16470 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
16480 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
16490 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
164a0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
164b0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
164c0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
164d0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
164e0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
164f0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
16500 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
16510 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
16520 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
16530 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
16540 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
16550 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
16560 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
16570 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
16580 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
16590 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72  mn_bytes() .** r
165a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
165b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
165c0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
165d0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66  or string..** If
165e0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
165f0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
16600 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
16610 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
16620 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
16630 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
16640 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
16650 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
16660 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
16670 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
16680 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
16690 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
166a0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
166b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
166c0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
166d0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
166e0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
166f0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
16700 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
16710 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65  t string..** The
16720 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
16730 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
16740 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
16750 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a  ator at the end.
16760 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
16770 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20  .  For clarity: 
16780 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
16790 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ed is the number
167a0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
167b0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
167c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
167d0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
167e0 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
167f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
16800 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
16810 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
16820 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 7a  t16(),.** even z
16830 65 72 6f 2d 6c 65 6e 67 74 68 20 73 74 72 69 6e  ero-length strin
16840 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
16850 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
16860 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76   The return.** v
16870 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
16880 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
16890 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
168a0 68 20 62 6c 6f 62 20 69 73 20 61 6e 20 61 72 62  h blob is an arb
168b0 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65  itrary.** pointe
168c0 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e  r, possibly even
168d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
168e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
168f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
16900 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  6() routine is s
16910 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65  imilar to sqlite
16920 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
16930 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74  .** but leaves t
16940 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46  he result in UTF
16950 2d 31 36 20 69 6e 73 74 65 61 64 20 6f 66 20 55  -16 instead of U
16960 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a  TF-8.  .** The z
16970 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
16980 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
16990 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a  n this count..**
169a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
169b0 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
169c0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
169d0 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
169e0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
169f0 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
16a00 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
16a10 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
16a20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
16a30 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
16a40 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
16a50 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
16a60 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65  rnally to do the
16a70 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61   conversion.** a
16a80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
16a90 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
16aa0 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
16ab0 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68 61 74 0a  onversions that.
16ac0 2a 2a 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  ** are applied:.
16ad0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
16ae0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
16af0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
16b00 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
16b10 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
16b20 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
16b30 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
16b40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
16b50 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
16b60 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
16b70 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
16b80 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
16b90 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
16ba0 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
16bb0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
16bc0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
16bd0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
16be0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
16bf0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
16c00 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
16c10 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
16c20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
16c30 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
16c40 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
16c50 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
16c60 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
16c70 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
16c80 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
16c90 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
16ca0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
16cb0 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
16cc0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
16cd0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
16ce0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72  <td> Same as for
16cf0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
16d00 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
16d10 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
16d20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
16d30 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
16d40 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
16d50 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
16d60 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
16d70 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
16d80 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
16d90 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
16da0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
16db0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
16dc0 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
16dd0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
16de0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
16df0 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
16e00 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
16e10 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
16e20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
16e30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
16e40 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
16e50 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
16e60 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
16e70 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
16e80 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
16e90 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
16ea0 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
16eb0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
16ec0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
16ed0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
16ee0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
16ef0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
16f00 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
16f10 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
16f20 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
16f30 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
16f40 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
16f50 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
16f60 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
16f70 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
16f80 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
16f90 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
16fa0 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
16fb0 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
16fc0 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
16fd0 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
16fe0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
16ff0 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e  .** on equavalen
17000 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
17010 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
17020 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
17030 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
17040 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
17050 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
17060 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
17070 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
17080 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
17090 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
170a0 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
170b0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
170c0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
170d0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
170e0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
170f0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
17100 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
17110 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
17120 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
17130 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
17140 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20  dated. .** Type 
17150 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
17160 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
17170 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
17180 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
17190 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
171a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c  ** <ul>.** <li><
171b0 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20  p>  The initial 
171c0 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
171d0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
171e0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20  lumn_text() .** 
171f0 20 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c 69           or sqli
17200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
17210 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
17220 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
17230 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
17240 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
17250 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
17260 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a  ng.</p></li>.**.
17270 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20  ** <li><p>  The 
17280 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
17290 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
172a0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
172b0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
172c0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
172d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
172e0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
172f0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
17300 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
17310 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31          to UTF-1
17320 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  6.</p></li>.**.*
17330 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69  * <li><p>  The i
17340 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
17350 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
17360 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
17370 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
17380 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
17390 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
173a0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
173b0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
173c0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
173d0 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70      to UTF-8.</p
173e0 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ></li>.** </ul>.
173f0 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e  **.** Conversion
17400 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
17410 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
17420 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
17430 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
17440 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
17450 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
17460 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
17470 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
17480 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
17490 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
174a0 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74  pointer points t
174b0 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  o will have been
174c0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
174d0 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
174e0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
174f0 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
17500 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
17510 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 20  but sometime it 
17520 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
17530 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
17540 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
17550 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
17560 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  ated.  .**.** Th
17570 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
17580 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
17590 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
175a0 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
175b0 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
175c0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
175d0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e  ays:.**.**  <ul>
175e0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
175f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
17600 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
17610 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
17620 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
17630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
17640 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
17650 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
17660 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
17670 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
17680 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
17690 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
176a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
176b0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e  )</li>.**  </ul>
176c0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
176d0 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
176e0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
176f0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71  olumn_text(), sq
17700 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
17710 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  b(),.** or sqlit
17720 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
17730 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
17740 65 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  e the result int
17750 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a 2a  o the desired.**
17760 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
17770 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
17780 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 73  umn_bytes() or s
17790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
177a0 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69  tes16() to.** fi
177b0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
177c0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
177d0 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73  ot mix call to s
177e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
177f0 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  xt() or.** sqlit
17800 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
17810 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
17820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
17830 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64 6f  tes16().  And do
17840 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c   not.** mix call
17850 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
17860 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69 74  umn_text16() wit
17870 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
17880 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
17890 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  )..**.** The poi
178a0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
178b0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
178c0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
178d0 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
178e0 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
178f0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
17900 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
17910 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
17920 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
17930 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
17940 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  ed.  The memory 
17950 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
17960 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
17970 64 20 62 6c 6f 62 73 20 69 73 20 66 72 65 65 64  d blobs is freed
17980 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
17990 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
179a0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
179b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
179c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
179d0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
179e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
179f0 74 63 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71  tc. into .** [sq
17a00 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
17a10 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79  *.** If a memory
17a20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
17a30 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
17a40 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
17a50 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
17a60 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
17a70 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
17a80 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
17a90 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
17aa0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
17ab0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
17ac0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
17ad0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
17ae0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
17af0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
17b00 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
17b10 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
17b20 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
17b30 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  EM]..*/.const vo
17b40 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
17b50 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
17b60 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
17b70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
17b80 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
17b90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
17ba0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
17bb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
17bc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
17bd0 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
17be0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
17bf0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
17c00 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
17c10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
17c20 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
17c30 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
17c40 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
17c50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
17c60 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
17c70 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
17c80 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
17c90 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
17ca0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
17cb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
17cc0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
17cd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
17ce0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
17cf0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
17d00 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
17d10 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
17d20 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
17d30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
17d40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
17d50 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
17d60 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
17d70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
17d80 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
17d90 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
17da0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
17db0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
17dc0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
17dd0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a  ed to delete a .
17de0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
17df0 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20   | compiled SQL 
17e00 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74  statement]. If t
17e10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
17e20 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73 75 63  .** executed suc
17e30 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f  cessfully, or no
17e40 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c  t executed at al
17e50 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f  l, then SQLITE_O
17e60 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  K is returned..*
17e70 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f  * If execution o
17e80 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
17e90 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a  failed then an .
17ea0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
17eb0 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f   | error code] o
17ec0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
17ed0 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
17ee0 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69  error code].** i
17ef0 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a  s returned. .**.
17f00 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
17f10 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
17f20 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
17f30 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
17f40 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
17f50 65 33 5f 73 74 6d 74 20 7c 20 76 69 72 74 75 61  e3_stmt | virtua
17f60 6c 20 6d 61 63 68 69 6e 65 5d 2e 20 20 49 66 20  l machine].  If 
17f70 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
17f80 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  ine has not .** 
17f90 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
17fa0 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f  ion when this ro
17fb0 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c  utine is called,
17fc0 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a   that is like.**
17fd0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e   encountering an
17fe0 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74   error or an int
17ff0 65 72 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73  errupt.  (See [s
18000 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18010 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70  ()].) .** Incomp
18020 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79  lete updates may
18030 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
18040 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  and transactions
18050 20 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a   cancelled,  .**
18060 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
18070 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
18080 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 53 51   and the .** [SQ
18090 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73  LITE_ERROR | res
180a0 75 6c 74 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ult code] return
180b0 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
180c0 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e  TE_ABORT]..*/.in
180d0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
180e0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
180f0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
18100 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
18110 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
18120 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
18130 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
18140 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
18150 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
18160 74 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t a .** [sqlite3
18170 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
18180 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20   SQL statement] 
18190 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20  object..** back 
181a0 74 6f 20 69 74 27 73 20 69 6e 69 74 69 61 6c 20  to it's initial 
181b0 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
181c0 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
181d0 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65  ** Any SQL state
181e0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
181f0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
18200 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
18210 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
18220 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
18230 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
18240 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
18250 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
18260 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
18270 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
18280 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
18290 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
182a0 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
182b0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
182c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
182d0 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
182e0 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
182f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
18300 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
18310 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
18320 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
18330 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a  or aggregates.**
18340 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
18350 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
18360 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
18370 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
18380 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69  ates.  The.** di
18390 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65  fference only be
183a0 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73  tween the two is
183b0 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
183c0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a   parameter, the.
183d0 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  ** name of the (
183e0 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
183f0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 69   or aggregate, i
18400 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
18410 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
18420 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
18430 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20 66  n() and UTF-16 f
18440 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
18450 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
18460 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
18470 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
18480 5b 73 71 6c 69 74 65 33 20 7c 20 64 61 74 61 62  [sqlite3 | datab
18490 61 73 65 20 68 61 6e 64 6c 65 5d 20 74 68 61 74  ase handle] that
184a0 20 68 6f 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51   holds the.** SQ
184b0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
184c0 67 72 65 67 61 74 65 20 69 73 20 74 6f 20 62 65  gregate is to be
184d0 20 61 64 64 65 64 20 6f 72 20 72 65 64 65 66 69   added or redefi
184e0 6e 65 64 2e 20 49 66 20 61 20 73 69 6e 67 6c 65  ned. If a single
184f0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
18500 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
18510 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69  atabase handle i
18520 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20  nternally, then 
18530 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  SQL.** functions
18540 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6d   or aggregates m
18550 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64  ust be added ind
18560 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63  ividually to eac
18570 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61  h database.** ha
18580 6e 64 6c 65 20 77 69 74 68 20 77 68 69 63 68 20  ndle with which 
18590 74 68 65 79 20 77 69 6c 6c 20 62 65 20 75 73 65  they will be use
185a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
185b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
185c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
185d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
185e0 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f   be created.** o
185f0 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  r redefined..** 
18600 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
18610 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
18620 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
18630 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
18640 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   .** zero-termin
18650 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
18660 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
18670 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
18680 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
18690 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65  cters.  Any atte
186a0 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
186b0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
186c0 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
186d0 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  ill result in an
186e0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72   SQLITE_ERROR er
186f0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ror..**.** The t
18700 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
18710 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
18720 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
18730 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
18740 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
18750 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70  takes. If this p
18760 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
18770 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53  tive, then the S
18780 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
18790 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
187a0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
187b0 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  of arguments..**
187c0 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
187d0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
187e0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
187f0 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  at .** [SQLITE_U
18800 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
18810 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
18820 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
18830 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
18840 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
18850 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
18860 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
18870 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
18880 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
18890 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
188a0 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
188b0 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
188c0 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
188d0 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
188e0 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
188f0 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20  an another.  It 
18900 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a  is allowed to.**
18910 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
18920 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
18930 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
18940 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
18950 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
18960 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
18970 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
18980 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
18990 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
189a0 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  .** When multipl
189b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
189c0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
189d0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
189e0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
189f0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
18a00 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
18a10 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
18a20 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
18a30 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
18a40 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
18a50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
18a60 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
18a70 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78  care what.** tex
18a80 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  t encoding is us
18a90 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
18aa0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
18ab0 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54  uld be.** [SQLIT
18ac0 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  E_ANY]..**.** Th
18ad0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
18ae0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
18af0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
18b00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
18b10 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * of the functio
18b20 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
18b30 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
18b40 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  r using.** [sqli
18b50 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
18b60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65  ..**.** The seve
18b70 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20  nth, eighth and 
18b80 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73  ninth parameters
18b90 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
18ba0 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
18bb0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
18bc0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
18bd0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
18be0 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  t the SQL.** fun
18bf0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
18c00 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c  te. A scalar SQL
18c10 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
18c20 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
18c30 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78  tion of.** the x
18c40 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  Func callback on
18c50 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly, NULL pointer
18c60 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  s should be pass
18c70 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 0a  ed as the xStep.
18c80 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61  ** and xFinal pa
18c90 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67  rameters. An agg
18ca0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
18cb0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
18cc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
18cd0 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78  * of xStep and x
18ce0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73  Final and NULL s
18cf0 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
18d00 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65  for xFunc. To de
18d10 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74  lete an.** exist
18d20 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
18d30 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
18d40 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c  ass NULL for all
18d50 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
18d60 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ** callback..**.
18d70 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74  ** It is permitt
18d80 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
18d90 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
18da0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
18db0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
18dc0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
18dd0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
18de0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
18df0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
18e00 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
18e10 6e 67 20 70 65 72 66 65 72 72 65 64 20 74 65 78  ng perferred tex
18e20 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51  t encodings.  SQ
18e30 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
18e40 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
18e50 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  ion most closely
18e60 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
18e70 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
18e80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
18e90 20 75 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71   used..*/.int sq
18ea0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
18eb0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
18ec0 20 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   *,.  const char
18ed0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
18ee0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
18ef0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
18f00 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78  oid*,.  void (*x
18f10 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
18f20 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
18f30 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
18f40 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
18f50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
18f60 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
18f70 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
18f80 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
18f90 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
18fa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
18fb0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
18fc0 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e3*,.  const voi
18fd0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
18fe0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
18ff0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
19000 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a  void*,.  void (*
19010 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
19020 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
19030 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
19040 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
19050 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
19060 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
19070 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
19080 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
19090 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
190a0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
190b0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
190c0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
190d0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
190e0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
190f0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
19100 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
19110 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
19120 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
19130 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
19140 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
19150 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
19160 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
19170 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
19180 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
19190 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
191a0 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
191b0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
191c0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
191d0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
191e0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
191f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
19200 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
19210 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
19220 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
19230 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
19240 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
19250 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
19260 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20  I3REF: Obsolete 
19270 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
19280 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
19290 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f  are all now obso
192a0 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20  lete.  In order 
192b0 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
192c0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
192d0 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
192e0 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69  r code, we conti
192f0 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a  nue to support.*
19300 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
19310 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  s.  However, new
19320 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f   development pro
19330 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f  jects should avo
19340 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
19350 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
19360 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
19370 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
19380 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
19390 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
193a0 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
193b0 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74  to tell you want
193c0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74   they do..*/.int
193d0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
193e0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
193f0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20  _context*);.int 
19400 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
19410 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
19420 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
19430 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
19440 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
19450 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
19460 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
19470 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76  recover(void);.v
19480 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
19490 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
194a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
194b0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
194c0 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
194d0 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
194e0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
194f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
19500 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
19510 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
19520 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
19530 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
19540 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
19550 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
19560 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
19570 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
19580 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
19590 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
195a0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
195b0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
195c0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
195d0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
195e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
195f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
19600 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
19610 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
19620 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
19630 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
19640 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
19650 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
19660 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
19670 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
19680 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
19690 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
196a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
196b0 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
196c0 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
196d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
196e0 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
196f0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
19700 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
19710 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
19720 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
19730 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
19740 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
19750 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
19760 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
19770 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
19780 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
19790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
197a0 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  umn_blob | sqlit
197b0 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74  e3_column_* rout
197c0 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74 68 61  ines] except tha
197d0 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  t .** these rout
197e0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
197f0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  le [sqlite3_valu
19800 65 2a 5d 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  e*] pointer inst
19810 65 61 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ead.** of an [sq
19820 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
19830 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
19840 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
19850 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
19860 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
19870 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
19880 74 72 61 63 74 73 20 61 20 55 54 46 31 36 20 73  tracts a UTF16 s
19890 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
198a0 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
198b0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
198c0 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73  chine.  The.** s
198d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
198e0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
198f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
19900 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
19910 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 31 36  ** extract UTF16
19920 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
19930 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
19940 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
19950 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ively..**.** The
19960 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
19970 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
19980 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
19990 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
199a0 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
199b0 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
199c0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
199d0 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
199e0 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
199f0 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
19a00 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
19a10 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
19a20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
19a30 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
19a40 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
19a50 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 72  formation (in or
19a60 64 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20  der.** words if 
19a70 74 68 65 20 76 61 6c 75 65 20 69 73 20 6f 72 69  the value is ori
19a80 67 69 6e 61 6c 20 61 20 73 74 72 69 6e 67 20 74  ginal a string t
19a90 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
19aa0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
19ab0 20 69 74 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74   it is done.  Ot
19ac0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
19ad0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54  rsion occurs.  T
19ae0 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  he .** [SQLITE_I
19af0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
19b00 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
19b10 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
19b20 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
19b30 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
19b40 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
19b50 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
19b60 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72  ter that.** is r
19b70 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
19b80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
19b90 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
19ba0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
19bb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
19bc0 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
19bd0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
19be0 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
19bf0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
19c00 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
19c10 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
19c20 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
19c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
19c40 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
19c50 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
19c60 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  6()].  .**.** Th
19c70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
19c80 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
19c90 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
19ca0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
19cb0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
19cc0 70 6c 69 65 64 20 74 68 65 20 73 71 6c 69 74 65  plied the sqlite
19cd0 33 5f 76 61 6c 75 65 2a 20 70 61 72 61 6d 65 74  3_value* paramet
19ce0 65 72 73 2e 0a 2a 2a 20 4f 72 2c 20 69 66 20 74  ers..** Or, if t
19cf0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
19d00 2a 20 61 72 67 75 6d 65 6e 74 20 63 6f 6d 65 73  * argument comes
19d10 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
19d20 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
19d30 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2c  )].** interface,
19d40 20 74 68 65 6e 20 74 68 65 73 65 20 72 6f 75 74   then these rout
19d50 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 20 63  ines should be c
19d60 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
19d70 61 6d 65 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ame thread.** th
19d80 61 74 20 72 61 6e 20 5b 73 71 6c 69 74 65 33 5f  at ran [sqlite3_
19d90 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 2e  column_value()].
19da0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
19db0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
19dc0 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
19dd0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
19de0 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
19df0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
19e00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
19e10 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
19e20 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
19e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
19e40 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
19e50 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
19e60 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
19e70 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
19e80 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
19e90 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
19ea0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
19eb0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
19ec0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
19ed0 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
19ee0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
19ef0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
19f00 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
19f10 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
19f20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
19f30 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
19f40 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
19f50 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
19f60 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
19f70 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
19f80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
19f90 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
19fa0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
19fb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
19fc0 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
19fd0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
19fe0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
19ff0 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
1a000 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a  tion Context.**.
1a010 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
1a020 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61  ation of aggrega
1a030 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
1a040 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   use this routin
1a050 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a  e to allocate.**
1a060 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72   a structure for
1a070 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
1a080 74 61 74 65 2e 20 20 54 68 65 20 66 69 72 73 74  tate.  The first
1a090 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
1a0a0 6e 65 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20  ne.** is called 
1a0b0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1a0c0 20 61 67 67 72 65 67 61 74 65 2c 20 61 20 6e 65   aggregate, a ne
1a0d0 77 20 73 74 72 75 63 74 75 72 65 20 6f 66 20 73  w structure of s
1a0e0 69 7a 65 20 6e 42 79 74 65 73 0a 2a 2a 20 69 73  ize nBytes.** is
1a0f0 20 61 6c 6c 6f 63 61 74 65 64 2c 20 7a 65 72 6f   allocated, zero
1a100 65 64 2c 20 61 6e 64 20 72 65 74 75 72 6e 65 64  ed, and returned
1a110 2e 20 20 4f 6e 20 73 75 62 73 65 71 75 65 6e 74  .  On subsequent
1a120 20 63 61 6c 6c 73 20 28 66 6f 72 20 74 68 65 0a   calls (for the.
1a130 2a 2a 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  ** same aggregat
1a140 65 20 69 6e 73 74 61 6e 63 65 29 20 74 68 65 20  e instance) the 
1a150 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
1a160 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 69 6d  eturned.  The im
1a170 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1a180 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
1a190 20 63 61 6e 20 75 73 65 20 74 68 65 20 72 65 74   can use the ret
1a1a0 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20  urned buffer to 
1a1b0 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e  accumulate data.
1a1c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 66 66 65  .**.** The buffe
1a1d0 72 20 61 6c 6c 6f 63 61 74 65 64 20 69 73 20 66  r allocated is f
1a1e0 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
1a1f0 6c 79 20 62 79 20 53 51 4c 69 74 65 20 77 68 61  ly by SQLite wha
1a200 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  n the aggregate.
1a210 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  ** query conclud
1a220 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
1a230 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68  rst parameter sh
1a240 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f  ould be a copy o
1a250 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  f the .** [sqlit
1a260 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
1a270 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
1a280 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
1a290 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1a2a0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1a2b0 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
1a2c0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
1a2d0 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
1a2e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
1a2f0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
1a300 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
1a310 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
1a320 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
1a330 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
1a340 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
1a350 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1a360 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
1a370 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
1a380 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
1a390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a3a0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
1a3b0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1a3c0 54 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  The pUserData pa
1a3d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
1a3e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
1a3f0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
1a400 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
1a410 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
1a420 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64  routines.** used
1a430 20 74 6f 20 72 65 67 69 73 74 65 72 20 75 73 65   to register use
1a440 72 20 66 75 6e 63 74 69 6f 6e 73 20 69 73 20 61  r functions is a
1a450 76 61 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a 20 74  vailable to.** t
1a460 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1a470 6e 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  n of the functio
1a480 6e 20 75 73 69 6e 67 20 74 68 69 73 20 63 61 6c  n using this cal
1a490 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  l..**.** This ro
1a4a0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
1a4b0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
1a4c0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
1a4d0 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
1a4e0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
1a4f0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
1a500 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
1a510 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
1a520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a530 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
1a540 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
1a550 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
1a560 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
1a570 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
1a580 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
1a590 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
1a5a0 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68 20 61  meta-data with a
1a5b0 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
1a5c0 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
1a5d0 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
1a5e0 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
1a5f0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
1a600 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
1a610 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
1a620 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
1a630 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
1a640 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
1a650 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d 61 79  ed meta-data may
1a660 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
1a670 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
1a680 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
1a690 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
1a6a0 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
1a6b0 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
1a6c0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
1a6d0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
1a6e0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
1a6f0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
1a700 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61  ed as.** meta-da
1a710 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
1a720 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
1a730 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
1a740 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
1a750 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
1a760 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
1a770 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
1a780 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
1a790 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
1a7a0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
1a7b0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
1a7c0 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
1a7d0 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
1a7e0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
1a7f0 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
1a800 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
1a810 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
1a820 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
1a830 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
1a840 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1a850 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 2d 64  er to the meta-d
1a860 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
1a870 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  d with the Nth a
1a880 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 20 74 6f  rgument value to
1a890 20 74 68 65 20 63 75 72 72 65 6e 74 20 53 51 4c   the current SQL
1a8a0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
1a8b0 6c 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  l, where N is th
1a8c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a8d0 65 72 2e 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64  er. If no meta-d
1a8e0 61 74 61 20 68 61 73 20 62 65 65 6e 20 73 65 74  ata has been set
1a8f0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 76 61 6c   for.** that val
1a900 75 65 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ue, then a NULL 
1a910 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
1a920 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
1a930 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
1a940 74 61 28 29 20 69 73 20 75 73 65 64 20 74 6f 20  ta() is used to 
1a950 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64  associate meta-d
1a960 61 74 61 20 77 69 74 68 20 61 6e 20 53 51 4c 0a  ata with an SQL.
1a970 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  ** function argu
1a980 6d 65 6e 74 2e 20 54 68 65 20 74 68 69 72 64 20  ment. The third 
1a990 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
1a9a0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
1a9b0 74 61 2d 64 61 74 61 0a 2a 2a 20 74 6f 20 62 65  ta-data.** to be
1a9c0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1a9d0 20 74 68 65 20 4e 74 68 20 75 73 65 72 20 66 75   the Nth user fu
1a9e0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 20  nction argument 
1a9f0 76 61 6c 75 65 2e 20 54 68 65 20 66 6f 75 72 74  value. The fourt
1aa00 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73  h.** parameter s
1aa10 70 65 63 69 66 69 65 73 20 61 20 64 65 73 74 72  pecifies a destr
1aa20 75 63 74 6f 72 20 74 68 61 74 20 77 69 6c 6c 20  uctor that will 
1aa30 62 65 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  be called on the
1aa40 20 6d 65 74 61 2d 0a 2a 2a 20 64 61 74 61 20 70   meta-.** data p
1aa50 6f 69 6e 74 65 72 20 74 6f 20 72 65 6c 65 61 73  ointer to releas
1aa60 65 20 69 74 20 77 68 65 6e 20 69 74 20 69 73 20  e it when it is 
1aa70 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
1aa80 65 64 2e 20 49 66 20 74 68 65 20 0a 2a 2a 20 64  ed. If the .** d
1aa90 65 73 74 72 75 63 74 6f 72 20 69 73 20 4e 55 4c  estructor is NUL
1aaa0 4c 2c 20 69 74 20 69 73 20 6e 6f 74 20 69 6e 76  L, it is not inv
1aab0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70  oked..**.** In p
1aac0 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61  ractice, meta-da
1aad0 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
1aae0 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
1aaf0 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
1ab00 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
1ab10 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
1ab20 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
1ab30 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
1ab40 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
1ab50 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a   SQL variables..
1ab60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1ab70 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
1ab80 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
1ab90 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
1aba0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
1abb0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
1abc0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1abd0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
1abe0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1abf0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
1ac00 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
1ac10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1ac20 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 76 6f  , int, void*, vo
1ac30 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
1ac40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ac50 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
1ac60 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
1ac70 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
1ac80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
1ac90 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 66   special value f
1aca0 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
1acb0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
1acc0 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
1acd0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
1ace0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
1acf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
1ad00 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64  ob()].  If the d
1ad10 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
1ad20 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
1ad30 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
1ad40 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
1ad50 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
1ad60 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
1ad70 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
1ad80 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
1ad90 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
1ada0 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49  d.  The .** SQLI
1adb0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
1adc0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
1add0 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
1ade0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
1adf0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
1ae00 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
1ae10 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
1ae20 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
1ae30 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
1ae40 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
1ae50 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
1ae60 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
1ae70 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
1ae80 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
1ae90 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
1aea0 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
1aeb0 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
1aec0 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
1aed0 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
1aee0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
1aef0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
1af00 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
1af10 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
1af20 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
1af30 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
1af40 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
1af50 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
1af60 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
1af70 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
1af80 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
1af90 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
1afa0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1afb0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
1afc0 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
1afd0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
1afe0 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
1aff0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
1b000 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
1b010 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1b020 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
1b030 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1b040 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
1b050 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
1b060 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1b070 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
1b080 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
1b090 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a 20  ch like the .** 
1b0a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1b0b0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
1b0c0 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20 66  d_*] family of f
1b0d0 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a 2a  unctions used.**
1b0e0 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
1b0f0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
1b100 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
1b110 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
1b120 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73  fer to the.** [s
1b130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1b140 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
1b150 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  * documentation]
1b160 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
1b170 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
1b180 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1b190 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
1b1a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
1b1b0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
1b1c0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
1b1d0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
1b1e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
1b1f0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
1b200 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 70 61 72  ion.  The.** par
1b210 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1b220 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
1b230 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
1b240 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
1b250 69 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  is the text of a
1b260 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
1b270 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1b280 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
1b290 28 29 20 63 61 75 73 65 20 74 68 65 20 66 75 6e  () cause the fun
1b2a0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
1b2b0 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 72 6f 77  tion.** to throw
1b2c0 20 61 6e 64 20 65 72 72 6f 72 20 69 6e 64 69 63   and error indic
1b2d0 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
1b2e0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
1b2f0 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70  o long.** to rep
1b300 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  resent..**.** Th
1b310 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
1b320 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
1b330 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
1b340 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
1b350 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
1b360 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1b370 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
1b380 65 78 74 5d 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  ext] pointer..*/
1b390 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1b3a0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
1b3b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
1b3c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
1b3d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
1b3e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1b3f0 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
1b400 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
1b410 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
1b420 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
1b430 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b440 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
1b450 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
1b460 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
1b470 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1b480 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1b490 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
1b4a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
1b4b0 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
1b4c0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
1b4d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
1b4e0 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
1b4f0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
1b500 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1b510 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
1b520 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
1b530 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1b540 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
1b550 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
1b560 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
1b570 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
1b580 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1b590 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
1b5a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
1b5b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
1b5c0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
1b5d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1b5e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1b5f0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
1b600 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
1b610 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
1b620 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1b630 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1b640 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
1b650 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b660 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1b670 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
1b680 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1b690 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
1b6a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1b6b0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1b6c0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
1b6d0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1b6e0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
1b6f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1b700 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
1b710 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1b720 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
1b730 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1b740 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
1b750 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
1b760 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
1b770 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68  quences.**.** Th
1b780 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
1b790 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
1b7a0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
1b7b0 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
1b7c0 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c  [sqlite3*] handl
1b7d0 65 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  e specified as t
1b7e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1b7f0 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  t. .**.** The na
1b800 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f  me of the new co
1b810 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1b820 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73   is specified as
1b830 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
1b840 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
1b850 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
1b860 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
1b870 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
1b880 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
1b890 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73  -16 string for s
1b8a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1b8b0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 20 49 6e  llation16().  In
1b8c0 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68   all cases.** th
1b8d0 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64  e name is passed
1b8e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   as the second f
1b8f0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
1b900 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
1b910 64 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  d argument must 
1b920 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
1b930 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
1b940 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTF8],.** [SQLIT
1b950 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53  E_UTF16LE] or [S
1b960 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
1b970 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
1b980 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
1b990 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70  d.** routine exp
1b9a0 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65  ects to be passe
1b9b0 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  d pointers to st
1b9c0 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73  rings encoded us
1b9d0 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54  ing UTF-8,.** UT
1b9e0 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
1b9f0 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  an or UTF-16 big
1ba00 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
1ba10 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f  vely..**.** A po
1ba20 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65  inter to the use
1ba30 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  r supplied routi
1ba40 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  ne must be passe
1ba50 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a  d as the fifth.*
1ba60 2a 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  * argument. If i
1ba70 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
1ba80 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
1ba90 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
1baa0 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
1bab0 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
1bac0 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
1bad0 20 61 6e 79 6d 6f 72 65 29 2e 20 45 61 63 68 20   anymore). Each 
1bae0 74 69 6d 65 20 74 68 65 20 75 73 65 72 0a 2a 2a  time the user.**
1baf0 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69   supplied functi
1bb00 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  on is invoked, i
1bb10 74 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f  t is passed a co
1bb20 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
1bb30 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
1bb40 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
1bb50 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
1bb60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f  te_collation() o
1bb70 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  r.** sqlite3_cre
1bb80 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
1bb90 29 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70  ) as its first p
1bba0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1bbb0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72  The remaining ar
1bbc0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 75  guments to the u
1bbd0 73 65 72 2d 73 75 70 70 6c 69 65 64 20 72 6f 75  ser-supplied rou
1bbe0 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72  tine are two str
1bbf0 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65  ings,.** each re
1bc00 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 5b  presented by a [
1bc10 6c 65 6e 67 74 68 2c 20 64 61 74 61 5d 20 70 61  length, data] pa
1bc20 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69  ir and encoded i
1bc30 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a  n the encoding.*
1bc40 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65  * that was passe
1bc50 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  d as the third a
1bc60 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65  rgument when the
1bc70 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
1bc80 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73  nce was.** regis
1bc90 74 65 72 65 64 2e 20 54 68 65 20 75 73 65 72 20  tered. The user 
1bca0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72  routine should r
1bcb0 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20  eturn negative, 
1bcc0 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65  zero or positive
1bcd0 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   if.** the first
1bce0 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
1bcf0 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
1bd00 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
1bd10 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74  the second.** st
1bd20 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49  ring. i.e. (STRI
1bd30 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a  NG1 - STRING2)..
1bd40 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1bd50 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1bd60 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
1bd70 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
1bd80 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
1bd90 20 65 78 63 61 70 74 20 74 68 61 74 20 69 74 20   excapt that it 
1bda0 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61  takes an extra a
1bdb0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
1bdc0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
1bdd0 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  r.** the collati
1bde0 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  on.  The destruc
1bdf0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
1be00 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
1be10 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
1be20 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
1be30 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
1be40 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
1be50 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
1be60 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
1be70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
1be80 32 28 29 2e 20 20 43 6f 6c 6c 61 74 69 6f 6e 73  2().  Collations
1be90 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
1bea0 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65 20  hen.** they are 
1beb0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
1bec0 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  ter calls to the
1bed0 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
1bee0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ion functions.**
1bef0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 73 71   or when the [sq
1bf00 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65  lite3*] database
1bf10 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73 65   handle is close
1bf20 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1bf30 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
1bf40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   The sqlite3_cre
1bf50 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
1bf60 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1bf70 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1bf80 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
1bf90 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
1bfa0 72 65 6c 65 61 73 65 73 2e 20 20 54 68 65 20 6f  releases.  The o
1bfb0 74 68 65 72 20 63 6f 6c 6c 61 74 69 6f 6e 20 63  ther collation c
1bfc0 72 65 61 74 69 6f 6e 0a 2a 2a 20 66 75 6e 63 74  reation.** funct
1bfd0 69 6f 6e 73 20 61 72 65 20 73 74 61 62 6c 65 2e  ions are stable.
1bfe0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1bff0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1c000 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
1c010 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
1c020 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
1c030 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
1c040 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
1c050 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1c060 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1c070 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
1c080 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1c090 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
1c0a0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
1c0b0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
1c0c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
1c0d0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
1c0e0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
1c0f0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
1c100 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
1c110 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
1c120 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
1c130 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1c140 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
1c150 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
1c160 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
1c170 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
1c180 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
1c190 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
1c1a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
1c1b0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
1c1c0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
1c1d0 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
1c1e0 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
1c1f0 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  .**.** To avoid 
1c200 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
1c210 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
1c220 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
1c230 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
1c240 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
1c250 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
1c260 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
1c270 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
1c280 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68  he.** database h
1c290 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c  andle to be call
1c2a0 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
1c2b0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
1c2c0 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a 2a  on sequence is.*
1c2d0 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  * required..**.*
1c2e0 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * If the functio
1c2f0 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
1c300 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
1c310 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
1c320 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
1c330 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
1c340 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
1c350 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
1c360 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
1c370 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
1c380 69 6e 20 55 54 46 2d 38 2e 20 49 66 20 73 71 6c  in UTF-8. If sql
1c390 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
1c3a0 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
1c3b0 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20  d, the names.** 
1c3c0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
1c3d0 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
1c3e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1c3f0 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  r. A call to eit
1c400 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  her.** function 
1c410 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69  replaces any exi
1c420 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a  sting callback..
1c430 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1c440 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1c450 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
1c460 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
1c470 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
1c480 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1c490 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
1c4a0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
1c4b0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
1c4c0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
1c4d0 28 29 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 61  (). The second a
1c4e0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
1c4f0 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c  atabase.** handl
1c500 65 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  e. The third arg
1c510 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
1c520 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
1c530 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
1c540 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
1c550 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
1c560 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
1c570 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
1c580 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
1c590 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
1c5a0 6e 20 72 65 71 75 69 72 65 64 2e 20 54 68 65 20  n required. The 
1c5b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1c5c0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1c5d0 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
1c5e0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1c5f0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ce..**.** The ca
1c600 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1c610 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
1c620 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
1c630 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
1c640 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1c650 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
1c660 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1c670 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
1c680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
1c690 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
1c6a0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1c6b0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1c6c0 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
1c6d0 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
1c6e0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
1c6f0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
1c700 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
1c710 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
1c720 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
1c730 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
1c740 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
1c750 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
1c760 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
1c770 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
1c780 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
1c790 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
1c7a0 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
1c7b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
1c7c0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
1c7d0 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
1c7e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
1c7f0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
1c800 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
1c810 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
1c820 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
1c830 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
1c840 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
1c850 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
1c860 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1c870 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1c880 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
1c890 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
1c8a0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
1c8b0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
1c8c0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
1c8d0 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
1c8e0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
1c8f0 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
1c900 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
1c910 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
1c920 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
1c930 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
1c940 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
1c950 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
1c960 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
1c970 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
1c980 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
1c990 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
1c9a0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
1c9b0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
1c9c0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
1c9d0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1c9e0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
1c9f0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1ca00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1ca10 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
1ca20 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
1ca30 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
1ca40 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
1ca50 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
1ca60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53  .** CAPI3REF:  S
1ca70 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
1ca80 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
1ca90 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  e.**.** This fun
1caa0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
1cab0 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
1cac0 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
1cad0 74 69 6f 6e 0a 2a 2a 20 61 20 6e 75 6d 62 65 72  tion.** a number
1cae0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
1caf0 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
1cb00 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
1cb10 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
1cb20 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
1cb30 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
1cb40 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 20  p requests with 
1cb50 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
1cb60 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
1cb70 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
1cb80 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
1cb90 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61  p to .** the nea
1cba0 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
1cbb0 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
1cbc0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1cbd0 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72 65   actually .** re
1cbe0 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
1cbf0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1cc00 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
1cc10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
1cc20 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65  ements this inte
1cc30 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67  rface by calling
1cc40 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a   the xSleep().**
1cc50 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
1cc60 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1cc70 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  vfs] object..*/.
1cc80 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  int sqlite3_slee
1cc90 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  p(int);../*.** C
1cca0 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65 20 4f  API3REF:  Name O
1ccb0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
1ccc0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
1ccd0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  iles.**.** If th
1cce0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
1ccf0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
1cd00 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
1cd10 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
1cd20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
1cd30 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74 6f 72   (a.ka. director
1cd40 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
1cd50 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
1cd60 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
1cd70 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  e will be placed
1cd80 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
1cd90 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72  ry.  If this var
1cda0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c  iable.** is NULL
1cdb0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
1cdc0 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73 65 61  QLite does a sea
1cdd0 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
1cde0 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61 72 79  priate temporary
1cdf0 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 74 6f  .** file directo
1ce00 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
1ce10 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69  not safe to modi
1ce20 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
1ce30 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61 73 65   once a database
1ce40 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68   connection.** h
1ce50 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  as been opened. 
1ce60 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
1ce70 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
1ce80 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
1ce90 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
1cea0 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
1ceb0 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
1cec0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
1ced0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
1cee0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61  have been call a
1cef0 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  nd remain unchan
1cf00 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a  ged thereafter..
1cf10 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
1cf20 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
1cf30 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
1cf40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cf50 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
1cf60 54 68 65 20 44 61 74 61 62 61 73 65 20 49 73 20  The Database Is 
1cf70 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  In Auto-Commit M
1cf80 6f 64 65 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20 74  ode.**.** Test t
1cf90 6f 20 73 65 65 20 77 68 65 74 68 65 72 20 6f 72  o see whether or
1cfa0 20 6e 6f 74 20 74 68 65 20 64 61 74 61 62 61 73   not the databas
1cfb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1cfc0 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a  in autocommit.**
1cfd0 20 6d 6f 64 65 2e 20 20 52 65 74 75 72 6e 20 54   mode.  Return T
1cfe0 52 55 45 20 69 66 20 69 74 20 69 73 20 61 6e 64  RUE if it is and
1cff0 20 46 41 4c 53 45 20 69 66 20 6e 6f 74 2e 20 20   FALSE if not.  
1d000 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
1d010 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61  is on.** by defa
1d020 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74  ult.  Autocommit
1d030 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1d040 61 20 42 45 47 49 4e 20 73 74 61 74 65 6d 65 6e  a BEGIN statemen
1d050 74 20 61 6e 64 20 72 65 65 6e 61 62 6c 65 64 0a  t and reenabled.
1d060 2a 2a 20 62 79 20 74 68 65 20 6e 65 78 74 20 43  ** by the next C
1d070 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43  OMMIT or ROLLBAC
1d080 4b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  K..**.** If anot
1d090 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
1d0a0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
1d0b0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
1d0c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
1d0d0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
1d0e0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
1d0f0 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
1d100 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
1d110 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
1d120 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
1d130 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
1d140 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1d150 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54 68 65  I3REF:  Find The
1d160 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
1d170 20 41 73 73 6f 63 69 61 74 65 64 20 57 69 74 68   Associated With
1d180 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
1d190 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75  ement.**.** Retu
1d1a0 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  rn the [sqlite3*
1d1b0 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  ] database handl
1d1c0 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20  e to which a.** 
1d1d0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
1d1e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1d1f0 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20  nt] belongs..** 
1d200 54 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  This is the same
1d210 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
1d220 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74 68 65   that was.** the
1d230 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1d240 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1d250 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d260 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a   its variants.**
1d270 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
1d280 6f 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  o create the sta
1d290 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
1d2a0 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
1d2b0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
1d2c0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
1d2d0 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _stmt*);.../*.**
1d2e0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
1d2f0 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
1d300 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
1d310 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  backs.**.** Thes
1d320 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65  e routines.** re
1d330 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1d340 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 62 65 20  functions to be 
1d350 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
1d360 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a   a transaction.*
1d370 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 20 6f  * is committed o
1d380 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20  r rolled back.  
1d390 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
1d3a0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
1d3b0 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ugh.** to the ca
1d3c0 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20  llback.  If the 
1d3d0 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
1d3e0 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
1d3f0 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  on .** returns n
1d400 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
1d410 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
1d420 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
1d430 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  lback..**.** If 
1d440 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  another function
1d450 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20   was previously 
1d460 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20  registered, its 
1d470 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65  pArg value is re
1d480 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72  turned..** Other
1d490 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74  wise NULL is ret
1d4a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  urned..**.** Reg
1d4b0 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20  istering a NULL 
1d4c0 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
1d4d0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  s the callback..
1d4e0 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
1d4f0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
1d500 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
1d510 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
1d520 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65  e been .** rolle
1d530 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
1d540 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
1d550 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
1d560 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
1d570 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
1d580 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
1d590 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
1d5a0 20 74 6f 20 6f 63 63 75 72 2e 20 54 68 65 20 0a   to occur. The .
1d5b0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ** callback is n
1d5c0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
1d5d0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61  transaction is a
1d5e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
1d5f0 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62 65 63 61  led.** back beca
1d600 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
1d610 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1d620 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
1d630 73 65 20 61 72 65 20 65 78 70 65 72 69 6d 65 6e  se are experimen
1d640 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
1d650 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74 20 74  nd are subject t
1d660 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69  o change..*/.voi
1d670 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
1d680 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
1d690 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
1d6a0 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
1d6b0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
1d6c0 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ook(sqlite3*, vo
1d6d0 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76  id(*)(void *), v
1d6e0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1d6f0 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61  PI3REF: Data Cha
1d700 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  nge Notification
1d710 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1d720 20 52 65 67 69 73 74 65 72 20 61 20 63 61 6c 6c   Register a call
1d730 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
1d740 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
1d750 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74  connection ident
1d760 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
1d770 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1d780 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
1d790 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
1d7a0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
1d7b0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
1d7c0 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
1d7d0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
1d7e0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e  call to this fun
1d7f0 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 61  ction for the sa
1d800 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  me .** database 
1d810 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
1d820 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
1d830 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1d840 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
1d850 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
1d860 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20   to invoke when 
1d870 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64  a .** row is upd
1d880 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
1d890 72 20 64 65 6c 65 74 65 64 2e 20 54 68 65 20 66  r deleted. The f
1d8a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1d8b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1d8c0 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68  .** a copy of th
1d8d0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1d8e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
1d8f0 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68 65 20 73  te_hook(). The s
1d900 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a  econd callback .
1d910 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ** argument is o
1d920 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f 49 4e 53  ne of SQLITE_INS
1d930 45 52 54 2c 20 53 51 4c 49 54 45 5f 44 45 4c 45  ERT, SQLITE_DELE
1d940 54 45 20 6f 72 20 53 51 4c 49 54 45 5f 55 50 44  TE or SQLITE_UPD
1d950 41 54 45 2c 20 64 65 70 65 6e 64 69 6e 67 0a 2a  ATE, depending.*
1d960 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  * on the operati
1d970 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
1d980 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62  he callback to b
1d990 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68 65 20 74  e invoked. The t
1d9a0 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75  hird and .** fou
1d9b0 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
1d9c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
1d9d0 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
1d9e0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  o the database a
1d9f0 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d  nd .** table nam
1da00 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
1da10 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 20 54   affected row. T
1da20 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63  he final callbac
1da30 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a  k parameter is .
1da40 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  ** the rowid of 
1da50 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20  the row. In the 
1da60 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
1da70 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 72  e, this is the r
1da80 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74  owid after .** t
1da90 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20  he update takes 
1daa0 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  place..**.** The
1dab0 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
1dac0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
1dad0 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
1dae0 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
1daf0 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
1db00 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
1db10 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
1db20 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
1db30 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
1db40 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
1db50 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20  tered, its pArg 
1db60 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
1db70 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20  d..** Otherwise 
1db80 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
1db90 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1dba0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
1dbb0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
1dbc0 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
1dbd0 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
1dbe0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
1dbf0 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
1dc00 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
1dc10 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65  API3REF:  Enable
1dc20 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
1dc30 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
1dc40 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1dc50 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
1dc60 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e  ables the sharin
1dc70 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  g of the databas
1dc80 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73  e cache.** and s
1dc90 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63  chema data struc
1dca0 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 63 6f  tures between co
1dcb0 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74 68 65  nnections to the
1dcc0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 0a   same database..
1dcd0 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e  ** Sharing is en
1dce0 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67  abled if the arg
1dcf0 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20 61 6e  ument is true an
1dd00 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68  d disabled if th
1dd10 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73  e argument.** is
1dd20 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 42 65   false..**.** Be
1dd30 67 69 6e 6e 69 6e 67 20 69 6e 20 53 51 4c 69 74  ginning in SQLit
1dd40 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c  e version 3.5.0,
1dd50 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 69   cache sharing i
1dd60 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69  s enabled and di
1dd70 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e  sabled.** for an
1dd80 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
1dd90 20 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69    In prior versi
1dda0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73  ons of SQLite, s
1ddb0 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e  haring was.** en
1ddc0 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
1ddd0 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
1dde0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
1ddf0 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68  .** The cache sh
1de00 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
1de10 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
1de20 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
1de30 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
1de40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1de50 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1de60 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
1de70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1de80 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
1de90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1dea0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
1deb0 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
1dec0 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 69 6e  e that was.** in
1ded0 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
1dee0 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
1def0 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74  ened..**.** Virt
1df00 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f  ual tables canno
1df10 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61  t be used with a
1df20 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20   shared cache.  
1df30 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63  When shared.** c
1df40 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c  ache is enabled,
1df50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
1df60 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41  eate_module()] A
1df70 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  PI used to regis
1df80 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  ter.** virtual t
1df90 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79  ables will alway
1dfa0 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  s return an erro
1dfb0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  r..**.** This ro
1dfc0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
1dfd0 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
1dfe0 72 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a  red cache was.**
1dff0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
1e000 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  bled successfull
1e010 79 2e 20 20 41 6e 20 5b 53 51 4c 49 54 45 5f 45  y.  An [SQLITE_E
1e020 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64  RROR | error cod
1e030 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  e].** is returne
1e040 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  d otherwise..**.
1e050 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20  ** Shared cache 
1e060 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1e070 65 66 61 75 6c 74 2e 20 20 42 75 74 20 74 68 69  efault.  But thi
1e080 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
1e090 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
1e0a0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
1e0b0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
1e0c0 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
1e0d0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
1e0e0 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
1e0f0 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
1e100 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1e110 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
1e120 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  he(int);../*.** 
1e130 43 41 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d  CAPI3REF:  Attem
1e140 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
1e150 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 41 74 74  Memory.**.** Att
1e160 65 6d 70 74 20 74 6f 20 66 72 65 65 20 4e 20 62  empt to free N b
1e170 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d  ytes of heap mem
1e180 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
1e190 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
1e1a0 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  l.** memory allo
1e1b0 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20  cations held by 
1e1c0 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
1e1d0 72 61 72 79 20 28 65 78 61 6d 70 6c 65 3a 20 6d  rary (example: m
1e1e0 65 6d 6f 72 79 20 0a 2a 2a 20 75 73 65 64 20 74  emory .** used t
1e1f0 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65  o cache database
1e200 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
1e210 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 29 2e 0a  e performance)..
1e220 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
1e230 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
1e240 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1e250 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c  REF:  Impose A L
1e260 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a  imit On Heap Siz
1e270 65 0a 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20 61 20  e.**.** Place a 
1e280 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20  "soft" limit on 
1e290 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65  the amount of he
1e2a0 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d  ap memory that m
1e2b0 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a  ay be allocated.
1e2c0 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 20 49  ** by SQLite.  I
1e2d0 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c  f an internal al
1e2e0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75  location is requ
1e2f0 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 77  ested .** that w
1e300 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 20  ould exceed the 
1e310 73 70 65 63 69 66 69 65 64 20 6c 69 6d 69 74 2c  specified limit,
1e320 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
1e330 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a  e_memory()] is.*
1e340 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72  * invoked one or
1e350 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
1e360 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
1e370 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
1e380 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61  ocation.** is ma
1e390 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  de..**.** The li
1e3a0 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73  mit is called "s
1e3b0 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66  oft", because if
1e3c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
1e3d0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e 6e  e_memory()] cann
1e3e0 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66 66 69  ot.** free suffi
1e3f0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20  cient memory to 
1e400 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69  prevent the limi
1e410 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63  t from being exc
1e420 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65  eeded,.** the me
1e430 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65  mory is allocate
1e440 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65  d anyway and the
1e450 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
1e460 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a  on proceeds..**.
1e470 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72  ** A negative or
1e480 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20   zero value for 
1e490 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  N means that the
1e4a0 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65  re is no soft he
1e4b0 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20  ap limit and.** 
1e4c0 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
1e4d0 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20  _memory()] will 
1e4e0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
1e4f0 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78  hen memory is ex
1e500 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20  hausted..** The 
1e510 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f  default value fo
1e520 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
1e530 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a  limit is zero..*
1e540 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  *.** SQLite make
1e550 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20  s a best effort 
1e560 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66  to honor the sof
1e570 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 42  t heap limit.  B
1e580 75 74 20 69 66 20 69 74 0a 2a 2a 20 69 73 20 75  ut if it.** is u
1e590 6e 61 62 6c 65 20 74 6f 20 72 65 64 75 63 65 20  nable to reduce 
1e5a0 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62 65 6c  memory usage bel
1e5b0 6f 77 20 74 68 65 20 73 6f 66 74 20 6c 69 6d 69  ow the soft limi
1e5c0 74 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c  t, execution wil
1e5d0 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69  l.** continue wi
1e5e0 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e  thout error or n
1e5f0 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68  otification.  Th
1e600 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69  is is why the li
1e610 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65  mit is .** calle
1e620 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  d a "soft" limit
1e630 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72  .  It is advisor
1e640 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  y only..**.** Th
1e650 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
1e660 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  t is implemented
1e670 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
1e680 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
1e690 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
1e6a0 2e 20 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  .  Only a single
1e6b0 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20 69 73   memory alarm is
1e6c0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
1e6d0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 69 6d 70  e default.** imp
1e6e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1e6f0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
1e700 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1e710 20 61 6c 73 6f 20 75 73 65 73 20 74 68 65 0a 2a   also uses the.*
1e720 2a 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20 69  * memory alarm i
1e730 6e 74 65 72 66 61 63 65 20 69 74 20 77 69 6c 6c  nterface it will
1e740 20 69 6e 74 65 72 66 65 72 65 20 77 69 74 68 20   interfere with 
1e750 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  the operation of
1e760 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61   the.** soft hea
1e770 70 20 6c 69 6d 69 74 20 61 6e 64 20 75 6e 64 65  p limit and unde
1e780 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 20 77  fined behavior w
1e790 69 6c 6c 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a  ill result.  .**
1e7a0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1e7b0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1e7c0 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  0, this routine 
1e7d0 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64  only constrained
1e7e0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
1e7f0 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69  llocated by a si
1e800 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68  ngle thread - th
1e810 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
1e820 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74   which this rout
1e830 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65  ine.** runs.  Be
1e840 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
1e850 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1e860 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  0, the soft heap
1e870 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70   limit is.** app
1e880 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65  lied to all thre
1e890 61 64 73 2e 20 20 54 68 65 20 76 61 6c 75 65 20  ads.  The value 
1e8a0 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68  specified for th
1e8b0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
1e8c0 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72  t.** is an upper
1e8d0 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f   bound on the to
1e8e0 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tal memory alloc
1e8f0 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68  ation for all th
1e900 72 65 61 64 73 2e 20 20 49 6e 0a 2a 2a 20 76 65  reads.  In.** ve
1e910 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72  rsion 3.5.0 ther
1e920 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73  e is no mechanis
1e930 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74  m for limiting t
1e940 68 65 20 68 65 61 70 20 75 73 61 67 65 20 66 6f  he heap usage fo
1e950 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20  r.** individual 
1e960 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64  threads..*/.void
1e970 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
1e980 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a  ap_limit(int);..
1e990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e9a0 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74   Extract Metadat
1e9b0 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e  a About A Column
1e9c0 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a   Of A Table.**.*
1e9d0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  * This routine.*
1e9e0 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64  * returns meta-d
1e9f0 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
1ea00 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
1ea10 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61   specific databa
1ea20 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65  se.** table acce
1ea30 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
1ea40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   connection hand
1ea50 6c 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  le passed as the
1ea60 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
1ea70 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  .** argument..**
1ea80 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69  .** The column i
1ea90 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
1eaa0 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
1eab0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
1eac0 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74  ameters to .** t
1ead0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  his function. Th
1eae0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1eaf0 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
1eb00 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1eb10 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
1eb20 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72  main", "temp" or
1eb30 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
1eb40 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
1eb50 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
1eb60 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
1eb70 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c  . If it is NULL,
1eb80 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
1eb90 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
1eba0 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
1ebb0 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
1ebc0 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
1ebd0 74 68 6d 20 61 73 20 74 68 65 20 64 61 74 61 62  thm as the datab
1ebe0 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20  ase engine uses 
1ebf0 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75  to .** resolve u
1ec00 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
1ec10 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
1ec20 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
1ec30 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1ec40 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
1ec50 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
1ec60 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a  e and column .**
1ec70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
1ec80 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
1ec90 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
1eca0 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
1ecb0 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62  meters .** may b
1ecc0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65  e NULL..**.** Me
1ecd0 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ta information i
1ece0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72  s returned by wr
1ecf0 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d  iting to the mem
1ed00 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61  ory locations pa
1ed10 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35  ssed as.** the 5
1ed20 74 68 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  th and subsequen
1ed30 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
1ed40 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41  this function. A
1ed50 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20  ny of these .** 
1ed60 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
1ed70 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20   NULL, in which 
1ed80 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70  case the corresp
1ed90 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f  onding element o
1eda0 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72  f meta .** infor
1edb0 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74  mation is ommitt
1edc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  ed..**.** <pre>.
1edd0 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20 20  ** Parameter    
1ede0 20 4f 75 74 70 75 74 20 54 79 70 65 20 20 20 20   Output Type    
1edf0 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a    Description.**
1ee00 20 2d 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 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68  ----.**.**   5th
1ee30 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63           const c
1ee40 68 61 72 2a 20 20 20 20 20 20 44 61 74 61 20 74  har*      Data t
1ee50 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20  ype.**   6th    
1ee60 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a       const char*
1ee70 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68        Name of th
1ee80 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  e default collat
1ee90 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a  ion sequence .**
1eea0 20 20 20 37 74 68 20 20 20 20 20 20 20 20 20 69     7th         i
1eeb0 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
1eec0 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
1eed0 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
1eee0 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
1eef0 20 20 38 74 68 20 20 20 20 20 20 20 20 20 69 6e    8th         in
1ef00 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54  t              T
1ef10 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d  rue if the colum
1ef20 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
1ef30 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
1ef40 20 20 39 74 68 20 20 20 20 20 20 20 20 20 69 6e    9th         in
1ef50 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54  t              T
1ef60 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d  rue if the colum
1ef70 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45  n is AUTOINCREME
1ef80 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a  NT.** </pre>.**.
1ef90 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79  **.** The memory
1efa0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
1efb0 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69  he character poi
1efc0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66  nters returned f
1efd0 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61  or the .** decla
1efe0 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20  ration type and 
1eff0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1f000 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79  ce is valid only
1f010 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
1f020 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20  .** call to any 
1f030 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74  sqlite API funct
1f040 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
1f050 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c  e specified tabl
1f060 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20  e is actually a 
1f070 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72  view, then an er
1f080 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1f090 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70  .**.** If the sp
1f0a0 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69  ecified column i
1f0b0 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22  s "rowid", "oid"
1f0c0 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e   or "_rowid_" an
1f0d0 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52  d an .** INTEGER
1f0e0 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c   PRIMARY KEY col
1f0f0 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70  umn has been exp
1f100 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
1f110 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
1f120 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  t .** parameters
1f130 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65   are set for the
1f140 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
1f150 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20  ared column. If 
1f160 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65  there is no.** e
1f170 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
1f180 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74  ed IPK column, t
1f190 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70  hen the output p
1f1a0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
1f1b0 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73  t as .** follows
1f1c0 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
1f1d0 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20       data type: 
1f1e0 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20  "INTEGER".**    
1f1f0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
1f200 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a  nce: "BINARY".**
1f210 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30       not null: 0
1f220 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20  .**     primary 
1f230 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75  key: 1.**     au
1f240 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a  to increment: 0.
1f250 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20  ** </pre>.**.** 
1f260 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
1f270 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f  y load one or mo
1f280 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20  re schemas from 
1f290 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20  database files. 
1f2a0 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f  If an.** error o
1f2b0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69  ccurs during thi
1f2c0 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  s process, or if
1f2d0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74   the requested t
1f2e0 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a  able or column.*
1f2f0 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e  * cannot be foun
1f300 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72  d, an SQLITE err
1f310 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
1f320 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ned and an error
1f330 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74   message.** left
1f340 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
1f350 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72   handle (to be r
1f360 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73  etrieved using s
1f370 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29  qlite3_errmsg())
1f380 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
1f390 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
1f3a0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
1f3b0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
1f3c0 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
1f3d0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
1f3e0 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63  METADATA preproc
1f3f0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
1f400 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
1f410 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
1f420 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71  n_metadata(.  sq
1f430 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1f440 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e            /* Con
1f450 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a  nection handle *
1f460 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1f470 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
1f480 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65  /* Database name
1f490 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f   or NULL */.  co
1f4a0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
1f4b0 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62  Name,     /* Tab
1f4c0 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e  le name */.  con
1f4d0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
1f4e0 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75  Name,    /* Colu
1f4f0 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61  mn name */.  cha
1f500 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61  r const **pzData
1f510 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50  Type,    /* OUTP
1f520 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74  UT: Declared dat
1f530 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72  a type */.  char
1f540 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53   const **pzCollS
1f550 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55  eq,     /* OUTPU
1f560 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  T: Collation seq
1f570 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  uence name */.  
1f580 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20  int *pNotNull,  
1f590 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
1f5a0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e  UTPUT: True if N
1f5b0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
1f5c0 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69  nt exists */.  i
1f5d0 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c  nt *pPrimaryKey,
1f5e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
1f5f0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
1f600 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20  lumn part of PK 
1f610 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69  */.  int *pAutoi
1f620 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nc              
1f630 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
1f640 20 69 66 20 63 6f 6c 75 6d 73 20 69 73 20 61 75   if colums is au
1f650 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a  to-increment */.
1f660 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f670 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  EF: Load An Exte
1f680 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74 65  nsion.**.** Atte
1f690 6d 70 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53  mpt to load an S
1f6a0 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
1f6b0 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65  library containe
1f6c0 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a  d in the file.**
1f6d0 20 7a 46 69 6c 65 2e 20 20 54 68 65 20 65 6e 74   zFile.  The ent
1f6e0 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f  ry point is zPro
1f6f0 63 2e 20 20 7a 50 72 6f 63 20 6d 61 79 20 62 65  c.  zProc may be
1f700 20 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65   0 in which case
1f710 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20   the.** name of 
1f720 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  the entry point 
1f730 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c  defaults to "sql
1f740 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69  ite3_extension_i
1f750 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  nit"..**.** Retu
1f760 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
1f770 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53  n success and [S
1f780 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
1f790 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77  something goes w
1f7a0 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  rong..**.** If a
1f7b0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
1f7c0 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
1f7d0 6f 74 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c 20  ot 0, then fill 
1f7e0 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a  *pzErrMsg with .
1f7f0 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ** error message
1f800 20 74 65 78 74 2e 20 20 54 68 65 20 63 61 6c 6c   text.  The call
1f810 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ing function sho
1f820 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
1f830 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69  mory.** by calli
1f840 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
1f850 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e  ()]..**.** Exten
1f860 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
1f870 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
1f880 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
1f890 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
1f8a0 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  n()].** prior to
1f8b0 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50   calling this AP
1f8c0 49 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69  I or an error wi
1f8d0 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a  ll be returned..
1f8e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
1f8f0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20  oad_extension(. 
1f900 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1f910 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74         /* Load t
1f920 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74  he extension int
1f930 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  o this database 
1f940 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20  connection */.  
1f950 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
1f960 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66  e,    /* Name of
1f970 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72   the shared libr
1f980 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65  ary containing e
1f990 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f  xtension */.  co
1f9a0 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c  nst char *zProc,
1f9b0 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69      /* Entry poi
1f9c0 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f  nt.  Derived fro
1f9d0 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a  m zFile if 0 */.
1f9e0 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73    char **pzErrMs
1f9f0 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65  g       /* Put e
1fa00 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72  rror message her
1fa10 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b  e if not 0 */.);
1fa20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fa30 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  :  Enable Or Dis
1fa40 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
1fa50 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f 20  oading.**.** So 
1fa60 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73  as not to open s
1fa70 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e  ecurity holes in
1fa80 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69   older applicati
1fa90 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ons that are.** 
1faa0 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65  unprepared to de
1fab0 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f  al with extensio
1fac0 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61  n loading, and a
1fad0 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73  s a means of dis
1fae0 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73  abling.** extens
1faf0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c  ion loading whil
1fb00 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65  e evaluating use
1fb10 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74  r-entered SQL, t
1fb20 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  he following.** 
1fb30 41 50 49 20 69 73 20 70 72 6f 76 69 64 65 64 20  API is provided 
1fb40 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c  to turn the [sql
1fb50 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
1fb60 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d  ion()] mechanism
1fb70 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20   on and.** off. 
1fb80 20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65   It is off by de
1fb90 66 61 75 6c 74 2e 20 20 53 65 65 20 74 69 63 6b  fault.  See tick
1fba0 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20  et #1863..**.** 
1fbb0 43 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  Call this routin
1fbc0 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20  e with onoff==1 
1fbd0 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f  to turn extensio
1fbe0 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20  n loading on.** 
1fbf0 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68  and call it with
1fc00 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72   onoff==0 to tur
1fc10 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67  n it back off ag
1fc20 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ain..*/.int sqli
1fc30 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
1fc40 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
1fc50 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
1fc60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1fc70 45 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65  EF: Make Arrange
1fc80 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74  ments To Automat
1fc90 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45  ically Load An E
1fca0 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 52  xtension.**.** R
1fcb0 65 67 69 73 74 65 72 20 61 6e 20 65 78 74 65 6e  egister an exten
1fcc0 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
1fcd0 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74   that is automat
1fce0 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a  ically invoked.*
1fcf0 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  * whenever a new
1fd00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1fd10 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75  tion is opened u
1fd20 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1fd30 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1fd40 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
1fd50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1fd60 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2()]..**.** This
1fd70 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f   API can be invo
1fd80 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73  ked at program s
1fd90 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20  tartup in order 
1fda0 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f  to register.** o
1fdb0 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69  ne or more stati
1fdc0 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74  cally linked ext
1fdd0 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c  ensions that wil
1fde0 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a  l be available.*
1fdf0 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74  * to all new dat
1fe00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fe10 73 2e 0a 2a 2a 0a 2a 2a 20 44 75 70 6c 69 63 61  s..**.** Duplica
1fe20 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72  te extensions ar
1fe30 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61  e detected so ca
1fe40 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
1fe50 6e 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  ne multiple.** t
1fe60 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
1fe70 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20  me extension is 
1fe80 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  harmless..**.** 
1fe90 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  This routine sto
1fea0 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  res a pointer to
1feb0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
1fec0 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74 68  n an array.** th
1fed0 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66  at is obtained f
1fee0 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2e 20 20 49  rom malloc().  I
1fef0 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f  f you run a memo
1ff00 72 79 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b  ry leak.** check
1ff10 65 72 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72  er on your progr
1ff20 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74  am and it report
1ff30 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65  s a leak because
1ff40 20 6f 66 20 74 68 69 73 0a 2a 2a 20 61 72 72 61   of this.** arra
1ff50 79 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b  y, then invoke [
1ff60 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d 61 74 69  sqlite3_automati
1ff70 63 5f 65 78 74 65 6e 73 69 6f 6e 5f 72 65 73 65  c_extension_rese
1ff80 74 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f  t()] prior.** to
1ff90 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65   shutdown to fre
1ffa0 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  e the memory..**
1ffb0 0a 2a 2a 20 41 75 74 6f 6d 61 74 69 63 20 65 78  .** Automatic ex
1ffc0 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
1ffd0 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
1ffe0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  s..**.** This in
1fff0 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
20000 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
20010 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
20020 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69   or.** removal i
20030 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
20040 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
20050 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f  int sqlite3_auto
20060 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20  _extension(void 
20070 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a  *xEntryPoint);..
20080 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20090 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63   Reset Automatic
200a0 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
200b0 6e 67 0a 2a 2a 0a 2a 2a 20 44 69 73 61 62 6c 65  ng.**.** Disable
200c0 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20   all previously 
200d0 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d  registered autom
200e0 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e  atic extensions.
200f0 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e    This.** routin
20100 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
20110 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72  ect of all prior
20120 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d 61   [sqlite3_automa
20130 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  tic_extension()]
20140 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a  .** calls..**.**
20150 20 54 68 69 73 20 63 61 6c 6c 20 64 69 73 61 62   This call disab
20160 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65 78  led automatic ex
20170 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20  tensions in all 
20180 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  threads..**.** T
20190 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
201a0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
201b0 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
201c0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d  change or.** rem
201d0 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72  oval in future r
201e0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
201f0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
20200 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
20210 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a  tension(void);..
20220 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52  ./*.****** EXPER
20230 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63  IMENTAL - subjec
20240 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
20250 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a  out notice *****
20260 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20  *********.**.** 
20270 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
20280 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
20290 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20  le mechanism is 
202a0 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
202b0 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
202c0 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
202d0 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
202e0 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
202f0 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
20300 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
20310 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
20320 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
20330 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
20340 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
20350 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
20360 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
20370 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  blizes, we will 
20380 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
20390 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
203a0 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
203b0 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
203c0 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
203d0 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
203e0 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
203f0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
20400 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
20410 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
20420 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
20430 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
20440 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
20450 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
20460 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
20470 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
20480 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
20490 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
204a0 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
204b0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
204c0 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
204d0 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 6d 6f 64  le;../*.** A mod
204e0 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73 20 6f  ule is a class o
204f0 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  f virtual tables
20500 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69  .  Each module i
20510 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20  s defined.** by 
20520 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
20530 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
20540 75 63 74 75 72 65 2e 20 20 54 68 69 73 20 73 74  ucture.  This st
20550 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73  ructure consists
20560 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65  .** mostly of me
20570 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
20580 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  dule..*/.struct 
20590 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
205a0 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
205b0 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65  .  int (*xCreate
205c0 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
205d0 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
205e0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
205f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
20600 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
20610 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
20620 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
20630 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
20640 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  xConnect)(sqlite
20650 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
20660 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
20670 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
20680 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
20690 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
206a0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
206b0 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
206c0 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64    int (*xBestInd
206d0 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ex)(sqlite3_vtab
206e0 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33   *pVTab, sqlite3
206f0 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20  _index_info*);. 
20700 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65   int (*xDisconne
20710 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ct)(sqlite3_vtab
20720 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
20730 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69  (*xDestroy)(sqli
20740 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
20750 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  ;.  int (*xOpen)
20760 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
20770 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74  VTab, sqlite3_vt
20780 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75  ab_cursor **ppCu
20790 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  rsor);.  int (*x
207a0 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
207b0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
207c0 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73  int (*xFilter)(s
207d0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
207e0 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c  or*, int idxNum,
207f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78   const char *idx
20800 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Str,.           
20810 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73       int argc, s
20820 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61  qlite3_value **a
20830 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e  rgv);.  int (*xN
20840 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ext)(sqlite3_vta
20850 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
20860 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65  t (*xEof)(sqlite
20870 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
20880 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e  .  int (*xColumn
20890 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
208a0 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
208b0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
208c0 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28    int (*xRowid)(
208d0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
208e0 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  sor*, sqlite3_in
208f0 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20  t64 *pRowid);.  
20900 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73  int (*xUpdate)(s
20910 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69  qlite3_vtab *, i
20920 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nt, sqlite3_valu
20930 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  e **, sqlite3_in
20940 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  t64 *);.  int (*
20950 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f  xBegin)(sqlite3_
20960 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
20970 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
20980 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
20990 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d  );.  int (*xComm
209a0 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  it)(sqlite3_vtab
209b0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
209c0 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c  (*xRollback)(sql
209d0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
209e0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64  );.  int (*xFind
209f0 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65  Function)(sqlite
20a00 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69  3_vtab *pVtab, i
20a10 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63  nt nArg, const c
20a20 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20  har *zName,.    
20a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20a40 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e     void (**pxFun
20a50 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
20a60 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
20a70 76 61 6c 75 65 2a 2a 29 2c 0a 20 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 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a   void **ppArg);.
20aa0 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
20ab0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
20ac0 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
20ad0 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a  r *zNew);.};../*
20ae0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
20af0 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
20b00 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62  ture and its sub
20b10 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73  structures is us
20b20 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e  ed to.** pass in
20b30 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61  formation into a
20b40 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72  nd receive the r
20b50 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42  eply from the xB
20b60 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68  estIndex.** meth
20b70 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  od of an sqlite3
20b80 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69  _module.  The fi
20b90 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70  elds under **Inp
20ba0 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a  uts** are the.**
20bb0 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74   inputs to xBest
20bc0 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65  Index and are re
20bd0 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49  ad-only.  xBestI
20be0 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73  ndex inserts its
20bf0 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
20c00 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a   the **Outputs**
20c10 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54   fields..**.** T
20c20 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
20c30 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57   array records W
20c40 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
20c50 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 0a 2a  traints of the.*
20c60 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20  * form:.**.**   
20c70 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20        column OP 
20c80 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65  expr.**.** Where
20c90 20 4f 50 20 69 73 20 3d 2c 20 3c 2c 20 3c 3d 2c   OP is =, <, <=,
20ca0 20 3e 2c 20 6f 72 20 3e 3d 2e 20 20 54 68 65 20   >, or >=.  The 
20cb0 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61  particular opera
20cc0 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  tor is stored.**
20cd0 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b   in aConstraint[
20ce0 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78  ].op.  The index
20cf0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
20d00 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a 20  s stored in .** 
20d10 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
20d20 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61  olumn.  aConstra
20d30 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
20d40 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
20d50 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
20d60 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
20d70 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
20d80 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
20d90 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
20da0 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
20db0 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a  it cannot..**.**
20dc0 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61   The optimizer a
20dd0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
20de0 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68  erts terms of th
20df0 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20  e form "expr OP 
20e00 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d  column".** and m
20e10 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c  akes other simpl
20e20 69 66 69 63 61 74 69 6e 6f 73 20 74 6f 20 74 68  ificatinos to th
20e30 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69  e WHERE clause i
20e40 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a  n an attempt to.
20e50 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57  ** get as many W
20e60 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
20e70 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20  s into the form 
20e80 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70  shown above as p
20e90 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20  ossible..** The 
20ea0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
20eb0 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
20ec0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
20ed0 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65  rms in the corre
20ee0 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20  ct.** form that 
20ef0 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 72  refer to the par
20f00 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
20f10 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72  table being quer
20f20 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72  ied..**.** Infor
20f30 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
20f40 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
20f50 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
20f60 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63  rderBy[]..** Eac
20f70 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72  h term of aOrder
20f80 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c  By records a col
20f90 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52  umn of the ORDER
20fa0 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a   BY clause..**.*
20fb0 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78  * The xBestIndex
20fc0 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
20fd0 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
20fe0 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
20ff0 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
21000 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
21010 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
21020 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65 78  r.  If argvIndex
21030 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  >0 then.** the r
21040 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  ight-hand side o
21050 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
21060 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  ing aConstraint[
21070 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a  ] is evaluated.*
21080 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68  * and becomes th
21090 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65  e argvIndex-th e
210a0 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49  ntry in argv.  I
210b0 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  f aConstraintUsa
210c0 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20  ge[].omit.** is 
210d0 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
210e0 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73  onstraint is ass
210f0 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79  umed to be fully
21100 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a   handled by the.
21110 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
21120 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63   and is not chec
21130 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c  ked again by SQL
21140 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ite..**.** The i
21150 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72  dxNum and idxPtr
21160 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f   values are reco
21170 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20  rded and passed 
21180 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a  into xFilter..**
21190 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
211a0 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20  is used to free 
211b0 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f  idxPtr if needTo
211c0 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72  FreeIdxPtr is tr
211d0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72  ue..**.** The or
211e0 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65  derByConsumed me
211f0 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20  ans that output 
21200 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c  from xFilter wil
21210 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
21220 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
21230 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
21240 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
21250 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
21260 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
21270 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
21280 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61  **.** The estima
21290 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
212a0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
212b0 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
212c0 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
212d0 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
212e0 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
212f0 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
21300 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
21310 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
21320 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
21330 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
21340 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
21350 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
21360 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
21370 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
21380 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
21390 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
213a0 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74  s */.  const int
213b0 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20   nConstraint;   
213c0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
213d0 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
213e0 72 61 69 6e 74 20 2a 2f 0a 20 20 63 6f 6e 73 74  raint */.  const
213f0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
21400 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
21410 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
21420 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
21430 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c    /* Column on l
21440 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
21450 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
21460 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
21470 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a  r op;         /*
21480 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72   Constraint oper
21490 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73  ator */.     uns
214a0 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c  igned char usabl
214b0 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69  e;     /* True i
214c0 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  f this constrain
214d0 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20  t is usable */. 
214e0 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66      int iTermOff
214f0 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  set;          /*
21500 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   Used internally
21510 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68   - xBestIndex sh
21520 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20  ould ignore */. 
21530 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e 73 74   } *const aConst
21540 72 61 69 6e 74 3b 20 20 20 20 20 20 2f 2a 20 54  raint;      /* T
21550 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c  able of WHERE cl
21560 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
21570 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74 20   */.  const int 
21580 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  nOrderBy;       
21590 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65   /* Number of te
215a0 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52  rms in the ORDER
215b0 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20   BY clause */.  
215c0 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
215d0 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72  ite3_index_order
215e0 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  by {.     int iC
215f0 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
21600 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75      /* Column nu
21610 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73  mber */.     uns
21620 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b  igned char desc;
21630 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66         /* True f
21640 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20  or DESC.  False 
21650 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20  for ASC. */.  } 
21660 2a 63 6f 6e 73 74 20 61 4f 72 64 65 72 42 79 3b  *const aOrderBy;
21670 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20           /* The 
21680 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
21690 2a 2f 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73  */..  /* Outputs
216a0 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
216b0 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
216c0 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20  raint_usage {.  
216d0 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b    int argvIndex;
216e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66             /* if
216f0 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20   >0, constraint 
21700 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20  is part of argv 
21710 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20  to xFilter */.  
21720 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
21730 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f  omit;      /* Do
21740 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74   not code a test
21750 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72   for this constr
21760 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e  aint */.  } *con
21770 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  st aConstraintUs
21780 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75  age;.  int idxNu
21790 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  m;              
217a0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64    /* Number used
217b0 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65   to identify the
217c0 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72   index */.  char
217d0 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20   *idxStr;       
217e0 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67         /* String
217f0 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69  , possibly obtai
21800 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
21810 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74  _malloc */.  int
21820 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
21830 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20  r;      /* Free 
21840 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c  idxStr using sql
21850 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74  ite3_free() if t
21860 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64  rue */.  int ord
21870 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20  erByConsumed;   
21880 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f      /* True if o
21890 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79  utput is already
218a0 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f   ordered */.  do
218b0 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f  uble estimatedCo
218c0 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69  st;      /* Esti
218d0 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73  mated cost of us
218e0 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a  ing this index *
218f0 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  /.};.#define SQL
21900 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
21910 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65  AINT_EQ    2.#de
21920 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
21930 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20  X_CONSTRAINT_GT 
21940 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
21950 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
21960 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65  AINT_LE    8.#de
21970 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
21980 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20  X_CONSTRAINT_LT 
21990 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
219a0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
219b0 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23  RAINT_GE    32.#
219c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
219d0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d  DEX_CONSTRAINT_M
219e0 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 54  ATCH 64../*.** T
219f0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
21a00 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  sed to register 
21a10 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d  a new module nam
21a20 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65  e with an SQLite
21a30 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
21a40 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75   Module names mu
21a50 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64  st be registered
21a60 20 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67   before creating
21a70 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20   new.** virtual 
21a80 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f  tables on the mo
21a90 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20  dule, or before 
21aa0 75 73 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e  using preexistin
21ab0 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  g virtual.** tab
21ac0 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  les of the modul
21ad0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
21ae0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
21af0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
21b00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
21b10 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
21b20 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
21b30 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
21b40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
21b50 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
21b60 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
21b70 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
21b80 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20  te3_module *,   
21b90 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
21ba0 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
21bb0 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 20  void *          
21bc0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c             /* Cl
21bd0 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
21be0 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
21bf0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73  /.);../*.** This
21c00 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e   routine is iden
21c10 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71 6c  tical to the sql
21c20 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
21c30 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f 76  le() method abov
21c40 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  e,.** except tha
21c50 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65  t it allows a de
21c60 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
21c70 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69 65  n to be specifie
21c80 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e  d. It is.** even
21c90 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74   more experiment
21ca0 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73 74  al than the rest
21cb0 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
21cc0 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69  tables API..*/.i
21cd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
21ce0 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73  e_module_v2(.  s
21cf0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
21d00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
21d10 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
21d20 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
21d30 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
21d40 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
21d50 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
21d60 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
21d70 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
21d80 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20  module *,    /* 
21d90 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
21da0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
21db0 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20   *,             
21dc0 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
21dd0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
21de0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20  e/xConnect */.  
21df0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
21e00 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f  void*)     /* Mo
21e10 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20  dule destructor 
21e20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a  function */.);..
21e30 2f 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75  /*.** Every modu
21e40 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
21e50 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
21e60 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  s of the followi
21e70 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  ng structure.** 
21e80 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61  to describe a pa
21e90 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
21ea0 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  e of the module.
21eb0 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20    Each subclass 
21ec0 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 79 6c 6f  will.** be taylo
21ed0 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69  red to the speci
21ee0 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65  fic needs of the
21ef0 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
21f00 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a 2a  tation.   The.**
21f10 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73   purpose of this
21f20 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74   superclass is t
21f30 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e  o define certain
21f40 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65   fields that are
21f50 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61 6c   common.** to al
21f60 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  l module impleme
21f70 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  ntations..**.** 
21f80 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d  Virtual tables m
21f90 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61  ethods can set a
21fa0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
21fb0 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a  by assigning a.*
21fc0 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  * string obtaine
21fd0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
21fe0 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72 72  printf() to zErr
21ff0 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64  Msg.  The method
22000 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20   should.** take 
22010 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72  care that any pr
22020 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72  ior string is fr
22030 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f  eed by a call to
22040 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 0a   sqlite3_free().
22050 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69  ** prior to assi
22060 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69  gning a new stri
22070 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  ng to zErrMsg.  
22080 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  After the error 
22090 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65  message.** is de
220a0 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68  livered up to th
220b0 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61  e client applica
220c0 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67  tion, the string
220d0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
220e0 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20  ically.** freed 
220f0 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  by sqlite3_free(
22100 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73  ) and the zErrMs
22110 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20  g field will be 
22120 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a  zeroed.  Note.**
22130 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d 70   that sqlite3_mp
22140 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
22150 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20 75  te3_free() are u
22160 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 4d  sed on the zErrM
22170 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e 63  sg field.** sinc
22180 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  e virtual tables
22190 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d   are commonly im
221a0 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f 61  plemented in loa
221b0 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73  dable extensions
221c0 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74   which.** do not
221d0 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f 20   have access to 
221e0 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 29  sqlite3MPrintf()
221f0 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65 28   or sqlite3Free(
22200 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  )..*/.struct sql
22210 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f  ite3_vtab {.  co
22220 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
22230 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a  le *pModule;  /*
22240 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20   The module for 
22250 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62  this virtual tab
22260 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66  le */.  int nRef
22270 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
22280 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
22290 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20  internally */.  
222a0 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20  char *zErrMsg;  
222b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
222c0 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65  /* Error message
222d0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70   from sqlite3_mp
222e0 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20  rintf() */.  /* 
222f0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
22300 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
22310 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
22320 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
22330 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76 65  ds */.};../* Eve
22340 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ry module implem
22350 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
22360 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20  subclass of the 
22370 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
22380 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69  ure.** to descri
22390 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20  be cursors that 
223a0 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76  point into the v
223b0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64  irtual table and
223c0 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20   are used.** to 
223d0 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65  loop through the
223e0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20   virtual table. 
223f0 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65   Cursors are cre
22400 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ated using the.*
22410 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f  * xOpen method o
22420 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45  f the module.  E
22430 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ach module imple
22440 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64  mentation will d
22450 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e  efine.** the con
22460 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72  tent of a cursor
22470 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75   structure to su
22480 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73  it its own needs
22490 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70  ..**.** This sup
224a0 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69  erclass exists i
224b0 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e  n order to defin
224c0 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20  e fields of the 
224d0 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61  cursor that.** a
224e0 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c  re common to all
224f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
22500 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
22510 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
22520 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62  {.  sqlite3_vtab
22530 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a   *pVtab;      /*
22540 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f   Virtual table o
22550 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f  f this cursor */
22560 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61  .  /* Virtual ta
22570 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
22580 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c  ons will typical
22590 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ly add additiona
225a0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a  l fields */.};..
225b0 2f 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74  /*.** The xCreat
225c0 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d  e and xConnect m
225d0 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75  ethods of a modu
225e0 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f  le use the follo
225f0 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64  wing API.** to d
22600 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61  eclare the forma
22610 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64  t (the names and
22620 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68   datatypes of th
22630 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a  e columns) of.**
22640 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
22650 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65  les they impleme
22660 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  nt..*/.int sqlit
22670 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
22680 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
22690 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62  char *zCreateTab
226a0 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72 74  le);../*.** Virt
226b0 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70  ual tables can p
226c0 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69  rovide alternati
226d0 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
226e0 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ns of functions.
226f0 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46 69  ** using the xFi
22700 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f  ndFunction metho
22710 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76  d.  But global v
22720 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65  ersions of those
22730 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75   functions.** mu
22740 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65  st exist in orde
22750 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64  r to be overload
22760 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  ed..**.** This A
22770 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20  PI makes sure a 
22780 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f  global version o
22790 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  f a function wit
227a0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
227b0 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65  * name and numbe
227c0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
227d0 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73  exists.  If no s
227e0 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69  uch function exi
227f0 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  sts.** before th
22800 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64  is API is called
22810 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  , a new function
22820 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68   is created.  Th
22830 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
22840 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66  .** of the new f
22850 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63  unction always c
22860 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69  auses an excepti
22870 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e  on to be thrown.
22880 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20    So.** the new 
22890 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  function is not 
228a0 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e  good for anythin
228b0 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74  g by itself.  It
228c0 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73  s only.** purpos
228d0 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61  e is to be a pla
228e0 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74 69  ce-holder functi
228f0 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  on that can be o
22900 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20  verloaded.** by 
22910 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a  virtual tables..
22920 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73  **.** This API s
22930 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65  hould be conside
22940 72 65 64 20 70 61 72 74 20 6f 66 20 74 68 65 20  red part of the 
22950 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
22960 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63  terface,.** whic
22970 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  h is experimenta
22980 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f  l and subject to
22990 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
229a0 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64  sqlite3_overload
229b0 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65  _function(sqlite
229c0 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
229d0 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e  zFuncName, int n
229e0 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  Arg);../*.** The
229f0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
22a00 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
22a10 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65  mechanism define
22a20 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70  d above (back up
22a30 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74  .** to a comment
22a40 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69   remarkably simi
22a50 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29  lar to this one)
22a60 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
22a70 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62  nsidered.** to b
22a80 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  e experimental. 
22a90 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d   The interface m
22aa0 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69  ight change in i
22ab0 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73  ncompatible ways
22ac0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20  ..** If this is 
22ad0 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f  a problem for yo
22ae0 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68  u, do not use th
22af0 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74  e interface at t
22b00 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  his time..**.** 
22b10 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c  When the virtual
22b20 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
22b30 20 73 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77   stablizes, we w
22b40 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a  ill declare the.
22b50 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78  ** interface fix
22b60 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69  ed, support it i
22b70 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64  ndefinitely, and
22b80 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d   remove this com
22b90 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20  ment..**.****** 
22ba0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73  EXPERIMENTAL - s
22bb0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
22bc0 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20   without notice 
22bd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
22be0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
22bf0 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41  F: A Handle To A
22c00 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a  n Open BLOB.**.*
22c10 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
22c20 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f   the following o
22c30 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
22c40 69 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a 20 72  is used to .** r
22c50 65 70 72 65 73 65 6e 74 20 61 6e 20 62 6c 6f 62  epresent an blob
22c60 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62 6c 6f 62  -handle.  A blob
22c70 2d 68 61 6e 64 6c 65 20 69 73 20 63 72 65 61 74  -handle is creat
22c80 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
22c90 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61  3_blob_open()] a
22ca0 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  nd destroyed by 
22cb0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
22cc0 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  ose()]..** The [
22cd0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
22ce0 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
22cf0 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
22d00 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61  interfaces.** ca
22d10 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61  n be used to rea
22d20 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c  d or write small
22d30 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20   subsections of 
22d40 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68 65  the blob..** The
22d50 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
22d60 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
22d70 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  e returns the si
22d80 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c 6f  ze of the.** blo
22d90 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74  b in bytes..*/.t
22da0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
22db0 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74  lite3_blob sqlit
22dc0 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_blob;../*.** 
22dd0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41  CAPI3REF: Open A
22de0 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d   BLOB For Increm
22df0 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20  ental I/O.**.** 
22e00 4f 70 65 6e 20 61 20 68 61 6e 64 6c 65 20 74 6f  Open a handle to
22e10 20 74 68 65 20 62 6c 6f 62 20 6c 6f 63 61 74 65   the blob locate
22e20 64 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20  d in row iRow,, 
22e30 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20  column zColumn, 
22e40 0a 2a 2a 20 74 61 62 6c 65 20 7a 54 61 62 6c 65  .** table zTable
22e50 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62   in database zDb
22e60 2e 20 69 2e 65 2e 20 74 68 65 20 73 61 6d 65 20  . i.e. the same 
22e70 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c 64 0a  blob that would.
22e80 2a 2a 20 62 65 20 73 65 6c 65 63 74 65 64 20 62  ** be selected b
22e90 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  y:.**.** <pre>.*
22ea0 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f  *     SELECT zCo
22eb0 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54  lumn FROM zDb.zT
22ec0 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77 69 64  able WHERE rowid
22ed0 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72   = iRow;.** </pr
22ee0 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e>.**.** If the 
22ef0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
22f00 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
22f10 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20   blob is opened 
22f20 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61 6e 64  for .** read and
22f30 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 49   write access. I
22f40 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68  f it is zero, th
22f50 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64  e blob is opened
22f60 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20 61 63   for read .** ac
22f70 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  cess..**.** On s
22f80 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
22f90 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OK] is returned 
22fa0 61 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20  and the new .** 
22fb0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
22fc0 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73 20  blob handle] is 
22fd0 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c  written to *ppBl
22fe0 6f 62 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65  ob..** Otherwise
22ff0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
23000 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a  s returned and .
23010 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69  ** any value wri
23020 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20  tten to *ppBlob 
23030 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
23040 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ed by the caller
23050 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  ..** This functi
23060 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61 74 61  on sets the data
23070 62 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f  base-handle erro
23080 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
23090 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65  ge.** accessible
230a0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
230b0 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71  rcode()] and [sq
230c0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
230d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
230e0 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c  blob_open(.  sql
230f0 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63  ite3*,.  const c
23100 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73  har *zDb,.  cons
23110 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a  t char *zTable,.
23120 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
23130 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33  olumn,.  sqlite3
23140 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69  _int64 iRow,.  i
23150 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69  nt flags,.  sqli
23160 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f  te3_blob **ppBlo
23170 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  b.);../*.** CAPI
23180 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42  3REF:  Close A B
23190 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  LOB Handle.**.**
231a0 20 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b   Close an open [
231b0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
231c0 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2f 0a  lob handle]..*/.
231d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
231e0 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62  _close(sqlite3_b
231f0 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
23200 41 50 49 33 52 45 46 3a 20 20 52 65 74 75 72 6e  API3REF:  Return
23210 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20   The Size Of An 
23220 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20  Open BLOB.**.** 
23230 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
23240 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20  in bytes of the 
23250 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c 65 20  blob accessible 
23260 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a 2a 2a  via the open .**
23270 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
23280 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61   blob-handle] pa
23290 73 73 65 64 20 61 73 20 61 6e 20 61 72 67 75 6d  ssed as an argum
232a0 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
232b0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73  te3_blob_bytes(s
232c0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
232d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
232e0 20 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d    Read Data From
232f0 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
23300 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tally.**.** This
23310 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
23320 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66  d to read data f
23330 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20  rom an open .** 
23340 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
23350 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74  blob-handle] int
23360 6f 20 61 20 63 61 6c 6c 65 72 20 73 75 70 70 6c  o a caller suppl
23370 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e  ied buffer..** n
23380 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
23390 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62  re copied into b
233a0 75 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f 6d 20  uffer.** z from 
233b0 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73  the open blob, s
233c0 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
233d0 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a  t iOffset..**.**
233e0 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c   On success, SQL
233f0 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
23400 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61  ed. Otherwise, a
23410 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
23420 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65 72 72  ROR | SQLite err
23430 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  or code] or an.*
23440 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  * [SQLITE_IOERR_
23450 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
23460 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
23470 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  eturned..*/.int 
23480 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
23490 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  d(sqlite3_blob *
234a0 2c 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e  , void *z, int n
234b0 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a  , int iOffset);.
234c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
234d0 20 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74    Write Data Int
234e0 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  o A BLOB Increme
234f0 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69  ntally.**.** Thi
23500 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
23510 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61  ed to write data
23520 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a   into an open .*
23530 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
23540 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 66  | blob-handle] f
23550 72 6f 6d 20 61 20 75 73 65 72 20 73 75 70 70 6c  rom a user suppl
23560 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e  ied buffer..** n
23570 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
23580 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74  re copied from t
23590 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69  he buffer.** poi
235a0 6e 74 65 64 20 74 6f 20 62 79 20 7a 20 69 6e 74  nted to by z int
235b0 6f 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c  o the open blob,
235c0 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
235d0 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
235e0 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
235f0 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68  e3_blob | blob-h
23600 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73  andle] passed as
23610 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
23620 65 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  ent.** was not o
23630 70 65 6e 65 64 20 66 6f 72 20 77 72 69 74 69 6e  pened for writin
23640 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72  g (the flags par
23650 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
23660 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a  e3_blob_open()].
23670 2a 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20 74  *** was zero), t
23680 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
23690 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  urns [SQLITE_REA
236a0 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  DONLY]..**.** Th
236b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
236c0 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  only modify the 
236d0 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20  contents of the 
236e0 62 6c 6f 62 2c 20 69 74 20 69 73 0a 2a 2a 20 6e  blob, it is.** n
236f0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69  ot possible to i
23700 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65  ncrease the size
23710 20 6f 66 20 61 20 62 6c 6f 62 20 75 73 69 6e 67   of a blob using
23720 20 74 68 69 73 20 41 50 49 2e 20 49 66 0a 2a 2a   this API. If.**
23730 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20   offset iOffset 
23740 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62  is less than n b
23750 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e  ytes from the en
23760 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a  d of the blob, .
23770 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
23780 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
23790 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
237a0 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  tten..**.** On s
237b0 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f  uccess, SQLITE_O
237c0 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f  K is returned. O
237d0 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a  therwise, an .**
237e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c   [SQLITE_ERROR |
237f0 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f   SQLite error co
23800 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  de] or an.** [SQ
23810 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
23820 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72  | extended error
23830 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
23840 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
23850 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71  e3_blob_write(sq
23860 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f  lite3_blob *, co
23870 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74  nst void *z, int
23880 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   n, int iOffset)
23890 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
238a0 46 3a 20 20 56 69 72 74 75 61 6c 20 46 69 6c 65  F:  Virtual File
238b0 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a   System Objects.
238c0 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20  **.** A virtual 
238d0 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29  filesystem (VFS)
238e0 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   is an [sqlite3_
238f0 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74  vfs] object.** t
23900 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20  hat SQLite uses 
23910 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77  to interact.** w
23920 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ith the underlyi
23930 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
23940 74 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69 6c 64  tem.  Most build
23950 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a  s come with a.**
23960 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20   single default 
23970 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72  VFS that is appr
23980 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20  opriate for the 
23990 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
239a0 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20  * New VFSes can 
239b0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  be registered an
239c0 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73  d existing VFSes
239d0 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74   can be unregist
239e0 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c  ered..** The fol
239f0 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
23a00 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a  s are provided..
23a10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
23a20 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74  3_vfs_find() int
23a30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
23a40 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46   pointer to a VF
23a50 53 20 67 69 76 65 6e 20 69 74 73 0a 2a 2a 20 6e  S given its.** n
23a60 61 6d 65 2e 20 20 4e 61 6d 65 73 20 61 72 65 20  ame.  Names are 
23a70 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 20  case sensitive. 
23a80 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
23a90 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a 2a 2a  match, a NULL.**
23aa0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
23ab0 72 6e 65 64 2e 20 20 49 66 20 7a 56 66 73 4e 61  rned.  If zVfsNa
23ac0 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  me is NULL then 
23ad0 74 68 65 20 64 65 66 61 75 6c 74 20 0a 2a 2a 20  the default .** 
23ae0 56 46 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e  VFS is returned.
23af0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73  .**.** New VFSes
23b00 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 20   are registered 
23b10 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73  with sqlite3_vfs
23b20 5f 72 65 67 69 73 74 65 72 28 29 2e 20 20 45 61  _register().  Ea
23b30 63 68 0a 2a 2a 20 6e 65 77 20 56 46 53 20 62 65  ch.** new VFS be
23b40 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c  comes the defaul
23b50 74 20 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b  t VFS if the mak
23b60 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65  eDflt flag is se
23b70 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20 56  t..** The same V
23b80 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  FS can be regist
23b90 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
23ba0 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75  mes without inju
23bb0 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20 61  ry..** To make a
23bc0 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69  n existing VFS i
23bd0 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20  nto the default 
23be0 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74  VFS, register it
23bf0 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74   again.** with t
23c00 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67  he makeDflt flag
23c10 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69   set.  If two di
23c20 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69  fferent VFSes wi
23c30 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e  th the.** same n
23c40 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72  ame are register
23c50 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ed, the behavior
23c60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
23c70 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72  If a.** VFS is r
23c80 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61  egistered with a
23c90 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55   name that is NU
23ca0 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73  LL or an empty s
23cb0 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74  tring,.** then t
23cc0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
23cd0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  ndefined..** .**
23ce0 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46   Unregister a VF
23cf0 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74  S with the sqlit
23d00 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
23d10 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  r() interface..*
23d20 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 6c 74  * If the default
23d30 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73 74   VFS is unregist
23d40 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46  ered, another VF
23d50 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a  S is chosen as.*
23d60 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20  * the default.  
23d70 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74  The choice for t
23d80 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61 72  he new VFS is ar
23d90 62 69 74 72 61 72 79 2e 0a 2a 2f 0a 73 71 6c 69  bitrary..*/.sqli
23da0 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33  te3_vfs *sqlite3
23db0 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20  _vfs_find(const 
23dc0 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b  char *zVfsName);
23dd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73  .int sqlite3_vfs
23de0 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65  _register(sqlite
23df0 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65  3_vfs*, int make
23e00 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74  Dflt);.int sqlit
23e10 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
23e20 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b  r(sqlite3_vfs*);
23e30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23e40 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20  : Mutexes.**.** 
23e50 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
23e60 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
23e70 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a  nes for thread.*
23e80 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  * synchronizatio
23e90 6e 2e 20 20 54 68 6f 75 67 68 20 74 68 65 79 20  n.  Though they 
23ea0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
23eb0 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
23ec0 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65   by SQLite, code
23ed0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
23ee0 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  nst SQLite is.**
23ef0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73   permitted to us
23f00 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
23f10 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
23f20 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  he SQLite source
23f30 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d   code contains m
23f40 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
23f50 74 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66 20 74  tations .** of t
23f60 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69  hese mutex routi
23f70 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72  nes.  An appropr
23f80 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iate implementat
23f90 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74  ion.** is select
23fa0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
23fb0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
23fc0 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
23fd0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
23fe0 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
23ff0 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
24000 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  core:.**.** <ul>
24010 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
24020 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c  E_MUTEX_OS2.** <
24030 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
24040 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c  EX_PTHREAD.** <l
24050 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
24060 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20  X_W32.** <li>   
24070 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f  SQLITE_MUTEX_NOO
24080 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  P.** </ul>.**.**
24090 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45   The SQLITE_MUTE
240a0 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74  X_NOOP implement
240b0 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f  ation is a set o
240c0 66 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20 74  f routines .** t
240d0 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c  hat does no real
240e0 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20   locking and is 
240f0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
24100 75 73 65 20 69 6e 20 0a 2a 2a 20 61 20 73 69 6e  use in .** a sin
24110 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70  gle-threaded app
24120 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53  lication.  The S
24130 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c  QLITE_MUTEX_OS2,
24140 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
24150 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51  _PTHREAD, and SQ
24160 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69  LITE_MUTEX_W32 i
24170 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
24180 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74  * are appropriat
24190 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 6f 73 2f  e for use on os/
241a0 32 2c 20 75 6e 69 78 2c 20 61 6e 64 20 77 69 6e  2, unix, and win
241b0 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  dows..** .** If 
241c0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
241d0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
241e0 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
241f0 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
24200 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
24210 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
24220 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
24230 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
24240 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
24250 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
24260 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 20 54   the library.  T
24270 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e 74 65  he.** mutex inte
24280 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 64  rface routines d
24290 65 66 69 6e 65 64 20 68 65 72 65 20 62 65 63 6f  efined here beco
242a0 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a 20 72  me external.** r
242b0 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74 68 65  eferences in the
242c0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
242d0 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c 65 6d  for which implem
242e0 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73  entations.** mus
242f0 74 20 62 65 20 70 72 6f 76 69 64 65 64 20 62 79  t be provided by
24300 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
24310 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69 74 79  .  This facility
24320 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20 61 70   allows an.** ap
24330 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 6c  plication that l
24340 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c  inks against SQL
24350 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65 20 69  ite to provide i
24360 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a 2a 20  ts own mutex.** 
24370 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
24380 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
24390 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 69   modify the SQLi
243a0 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  te core..**.** T
243b0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
243c0 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  _alloc() routine
243d0 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77   allocates a new
243e0 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65  .** mutex and re
243f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
24400 74 6f 20 69 74 2e 20 20 49 66 20 69 74 20 72 65  to it.  If it re
24410 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  turns NULL.** th
24420 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  at means that a 
24430 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20  mutex could not 
24440 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53  be allocated.  S
24450 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e  QLite.** will un
24460 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61  wind its stack a
24470 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  nd return an err
24480 6f 72 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  or.  The argumen
24490 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
244a0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73  mutex_alloc() is
244b0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
244c0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a  teger constants:
244d0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
244e0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
244f0 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20  X_FAST.** <li>  
24500 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
24510 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  URSIVE.** <li>  
24520 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
24530 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c  TIC_MASTER.** <l
24540 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
24550 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c  _STATIC_MEM.** <
24560 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
24570 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a  X_STATIC_MEM2.**
24580 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
24590 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a  TEX_STATIC_PRNG.
245a0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
245b0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
245c0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
245d0 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f  The first two co
245e0 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73 71  nstants cause sq
245f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
24600 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a  c() to create.**
24610 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 54   a new mutex.  T
24620 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20  he new mutex is 
24630 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53  recursive when S
24640 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
24650 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64  RSIVE.** is used
24660 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61   but not necessa
24670 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c  rily so when SQL
24680 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69  ITE_MUTEX_FAST i
24690 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  s used..** The m
246a0 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
246b0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
246c0 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74  d to make a dist
246d0 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
246e0 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
246f0 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51  RECURSIVE and SQ
24700 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
24710 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  if it does.** no
24720 74 20 77 61 6e 74 20 74 6f 2e 20 20 42 75 74 20  t want to.  But 
24730 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
24740 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75 72   request a recur
24750 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a  sive mutex in.**
24760 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74 20   cases where it 
24770 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65  really needs one
24780 2e 20 20 49 66 20 61 20 66 61 73 74 65 72 20 6e  .  If a faster n
24790 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74  on-recursive mut
247a0 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ex.** implementa
247b0 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
247c0 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c  e on the host pl
247d0 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65  atform, the mute
247e0 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d  x subsystem.** m
247f0 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 63 68  ight return such
24800 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70   a mutex in resp
24810 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d  onse to SQLITE_M
24820 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a  UTEX_FAST..**.**
24830 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77   The other allow
24840 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ed parameters to
24850 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
24860 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75  lloc() each retu
24870 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  rn.** a pointer 
24880 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65  to a static pree
24890 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20  xisting mutex.  
248a0 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75 74 65  Four static mute
248b0 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  xes are.** used 
248c0 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  by the current v
248d0 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
248e0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
248f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
24900 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  may add addition
24910 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  al static mutexe
24920 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78  s.  Static mutex
24930 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72  es are for inter
24940 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
24950 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c  Lite only.  Appl
24960 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
24970 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73  e SQLite mutexes
24980 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f   should.** use o
24990 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20  nly the dynamic 
249a0 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64  mutexes returned
249b0 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   by SQLITE_MUTEX
249c0 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49  _FAST or.** SQLI
249d0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
249e0 56 45 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  VE..**.** Note t
249f0 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68  hat if one of th
24a00 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  e dynamic mutex 
24a10 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49  parameters (SQLI
24a20 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
24a30 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   or SQLITE_MUTEX
24a40 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75  _RECURSIVE) is u
24a50 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33  sed then sqlite3
24a60 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a  _mutex_alloc().*
24a70 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66  * returns a diff
24a80 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65  erent mutex on e
24a90 76 65 72 79 20 63 61 6c 6c 2e 20 20 42 75 74 20  very call.  But 
24aa0 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 20 0a  for the static .
24ab0 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20  ** mutex types, 
24ac0 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69  the same mutex i
24ad0 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76  s returned on ev
24ae0 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61  ery call that ha
24af0 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79  s.** the same ty
24b00 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  pe number..**.**
24b10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
24b20 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
24b30 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
24b40 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
24b50 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
24b60 6d 75 74 65 78 2e 20 20 53 51 4c 69 74 65 20 69  mutex.  SQLite i
24b70 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61  s careful to dea
24b80 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a  llocate every.**
24b90 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74   dynamic mutex t
24ba0 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73  hat it allocates
24bb0 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d  .  The dynamic m
24bc0 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20  utexes must not 
24bd0 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65 20 77 68  be in .** use wh
24be0 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c  en they are deal
24bf0 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70  located.  Attemp
24c00 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61  ting to dealloca
24c10 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d  te a static.** m
24c20 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20  utex results in 
24c30 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
24c40 6f 72 2e 20 20 53 51 4c 69 74 65 20 6e 65 76 65  or.  SQLite neve
24c50 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a  r deallocates.**
24c60 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e   a static mutex.
24c70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24c80 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
24c90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
24ca0 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65  ex_try() routine
24cb0 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20  s attempt.** to 
24cc0 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 20  enter a mutex.  
24cd0 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
24ce0 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 74  d is already wit
24cf0 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a  hin the mutex,.*
24d00 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
24d10 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f  enter() will blo
24d20 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  ck and sqlite3_m
24d30 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20  utex_try() will 
24d40 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
24d50 5f 42 55 53 59 2e 20 20 54 68 65 20 73 71 6c 69  _BUSY.  The sqli
24d60 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
24d70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24d80 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 75  s SQLITE_OK.** u
24d90 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65  pon successful e
24da0 6e 74 72 79 2e 20 20 4d 75 74 65 78 65 73 20 63  ntry.  Mutexes c
24db0 72 65 61 74 65 64 20 75 73 69 6e 67 20 53 51 4c  reated using SQL
24dc0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
24dd0 49 56 45 20 63 61 6e 0a 2a 2a 20 62 65 20 65 6e  IVE can.** be en
24de0 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
24df0 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65  imes by the same
24e00 20 74 68 72 65 61 64 2e 20 20 49 6e 20 73 75 63   thread.  In suc
24e10 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20  h cases the,.** 
24e20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78  mutex must be ex
24e30 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75  ited an equal nu
24e40 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65  mber of times be
24e50 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72  fore another thr
24e60 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72  ead.** can enter
24e70 2e 20 20 49 66 20 74 68 65 20 73 61 6d 65 20 74  .  If the same t
24e80 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65  hread tries to e
24e90 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 20 6b  nter any other k
24ea0 69 6e 64 20 6f 66 20 6d 75 74 65 78 0a 2a 2a 20  ind of mutex.** 
24eb0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
24ec0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
24ed0 75 6e 64 65 66 69 6e 65 64 2e 20 20 20 53 51 4c  undefined.   SQL
24ee0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65  ite will never e
24ef0 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62  xhibit.** such b
24f00 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f  ehavior in its o
24f10 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65  wn use of mutexe
24f20 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79  s..**.** Some sy
24f30 73 74 65 6d 73 20 28 65 78 3a 20 77 69 6e 64 6f  stems (ex: windo
24f40 77 73 39 35 29 20 64 6f 20 6e 6f 74 20 74 68 65  ws95) do not the
24f50 20 6f 70 65 72 61 74 69 6f 6e 20 69 6d 70 6c 65   operation imple
24f60 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 73 71 6c  mented by.** sql
24f70 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
24f80 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74  .  On those syst
24f90 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74  ems, sqlite3_mut
24fa0 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 0a 2a 2a  ex_try() will.**
24fb0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53   always return S
24fc0 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54 68 65  QLITE_BUSY.  The
24fd0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c   SQLite core onl
24fe0 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73  y ever uses.** s
24ff0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
25000 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a  () as an optimiz
25010 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73  ation so this is
25020 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61   acceptable beha
25030 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  vior..**.** The 
25040 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
25050 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78  ave() routine ex
25060 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 74  its a mutex that
25070 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
25080 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68  ly entered by th
25090 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20  e same thread.  
250a0 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  The behavior.** 
250b0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20  is undefined if 
250c0 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74  the mutex is not
250d0 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
250e0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ed by the.** cal
250f0 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69  ling thread or i
25100 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
25110 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c 69  allocated.  SQLi
25120 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72  te will.** never
25130 20 64 6f 20 65 69 74 68 65 72 2e 0a 2a 2a 0a 2a   do either..**.*
25140 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
25150 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
25160 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
25170 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
25180 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74  ..*/.sqlite3_mut
25190 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65  ex *sqlite3_mute
251a0 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  x_alloc(int);.vo
251b0 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
251c0 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75  _free(sqlite3_mu
251d0 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
251e0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
251f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
25200 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
25210 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d  ex_try(sqlite3_m
25220 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
25230 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
25240 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
25250 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25260 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 63 61  F: Mutex Verifca
25270 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
25280 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25290 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64  mutex_held() and
252a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e   sqlite3_mutex_n
252b0 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65  otheld() routine
252c0 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65  s.** are intende
252d0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
252e0 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
252f0 65 6e 74 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ents.  The SQLit
25300 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20  e core.** never 
25310 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
25320 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64  nes except insid
25330 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e  e an assert() an
25340 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  d applications.*
25350 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f  * are advised to
25360 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64   follow the lead
25370 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 54   of the core.  T
25380 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20  he core only.** 
25390 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65  provides impleme
253a0 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  ntations for the
253b0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e  se routines when
253c0 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a   it is compiled.
253d0 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ** with the SQLI
253e0 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20  TE_DEBUG flag.  
253f0 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  External mutex i
25400 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
25410 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 75 69  * are only requi
25420 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20 74  red to provide t
25430 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 66  hese routines if
25440 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 69 73   SQLITE_DEBUG is
25450 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e 64 20  .** defined and 
25460 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e 6f 74  if NDEBUG is not
25470 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
25480 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73  These routines s
25490 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75  hould return tru
254a0 65 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69  e if the mutex i
254b0 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74  n their argument
254c0 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e  .** is held or n
254d0 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74  ot held, respect
254e0 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61  ively, by the ca
254f0 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a  lling thread..**
25500 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
25510 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65  tation is not re
25520 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64  quired to provid
25530 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  ed versions of t
25540 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  hese.** routines
25550 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77   that actually w
25560 6f 72 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  ork..** If the i
25570 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
25580 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77  es not provide w
25590 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f  orking.** versio
255a0 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ns of these rout
255b0 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 20  ines, it should 
255c0 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64 65  at least provide
255d0 20 73 74 75 62 73 0a 2a 2a 20 74 68 61 74 20 61   stubs.** that a
255e0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 72 75  lways return tru
255f0 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f  e so that one do
25600 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72 69  es not get spuri
25610 6f 75 73 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e  ous.** assertion
25620 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a   failures..**.**
25630 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   If the argument
25640 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
25650 78 5f 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55  x_held() is a NU
25660 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
25670 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73  ** the routine s
25680 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20  hould return 1. 
25690 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e   This seems coun
256a0 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69  ter-intuitive si
256b0 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74  nce.** clearly t
256c0 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20  he mutex cannot 
256d0 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f  be held if it do
256e0 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42  es not exist.  B
256f0 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65  ut the.** the re
25700 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64  ason the mutex d
25710 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73  oes not exist is
25720 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69   because the bui
25730 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69  ld is not.** usi
25740 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64  ng mutexes.  And
25750 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20   we do not want 
25760 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e  the assert() con
25770 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
25780 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  all to sqlite3_m
25790 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66  utex_held() to f
257a0 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65  ail, so a non-ze
257b0 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20  ro return is.** 
257c0 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
257d0 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 54 68  thing to do.  Th
257e0 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
257f0 6e 6f 74 68 65 6c 64 28 29 20 0a 2a 2a 20 69 6e  notheld() .** in
25800 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 61  terface should a
25810 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77 68 65  lso return 1 whe
25820 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70  n given a NULL p
25830 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  ointer..*/.int s
25840 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
25850 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  d(sqlite3_mutex*
25860 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  );.int sqlite3_m
25870 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c  utex_notheld(sql
25880 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f  ite3_mutex*);../
25890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
258a0 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a  utex Types.**.**
258b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   The [sqlite3_mu
258c0 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74  tex_alloc()] int
258d0 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73  erface takes a s
258e0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
258f0 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f  * which is one o
25900 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
25910 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2f 0a 23 64  constants..*/.#d
25920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
25930 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20  EX_FAST         
25940 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
25950 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
25960 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64  SIVE        1.#d
25970 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
25980 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
25990 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
259a0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
259b0 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f  C_MEM       3  /
259c0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
259d0 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
259e0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
259f0 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f  C_MEM2      4  /
25a00 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  * sqlite3_releas
25a10 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a 23 64  e_memory() */.#d
25a20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
25a30 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20  EX_STATIC_PRNG  
25a40 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
25a50 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64  3_random() */.#d
25a60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
25a70 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20  EX_STATIC_LRU   
25a80 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61      6  /* lru pa
25a90 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  ge list */../*.*
25aa0 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d  * CAPI3REF: Low-
25ab0 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66  Level Control Of
25ac0 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a   Database Files.
25ad0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
25ae0 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
25af0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  )] interface mak
25b00 65 73 20 61 20 64 69 72 65 63 74 20 63 61 6c 6c  es a direct call
25b10 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65   to the.** xFile
25b20 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66  Control method f
25b30 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
25b40 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
25b50 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ct associated.**
25b60 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
25b70 61 72 20 64 61 74 61 62 61 73 65 20 69 64 65 6e  ar database iden
25b80 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
25b90 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 20  cond argument.  
25ba0 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  The.** name of t
25bb0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 74  he database is t
25bc0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
25bd0 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
25be0 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72   by the.** <a hr
25bf0 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68 2e  ef="lang_attach.
25c00 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61 3e  html">ATTACH</a>
25c10 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 68 61   SQL command tha
25c20 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a 2a 20  t opened the.** 
25c30 64 61 74 61 62 61 73 65 2e 20 20 54 6f 20 63 6f  database.  To co
25c40 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64  ntrol the main d
25c50 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 75 73  atabase file, us
25c60 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e  e the name "main
25c70 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ".** or a NULL p
25c80 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 74 68 69  ointer.  The thi
25c90 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
25ca0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
25cb0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65 20   routine.** are 
25cc0 70 61 73 73 65 64 20 64 69 72 65 63 74 6c 79 20  passed directly 
25cd0 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 73  through to the s
25ce0 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
25cf0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a 2a  parameters of.**
25d00 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
25d10 6c 20 6d 65 74 68 6f 64 2e 20 20 54 68 65 20 72  l method.  The r
25d20 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
25d30 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a  he xFileControl.
25d40 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65  ** method become
25d50 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
25d60 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ue of this routi
25d70 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ne..**.** If the
25d80 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
25d90 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f 65 73  r (zDbName) does
25da0 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65 20 6e   not match the n
25db0 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70  ame of any.** op
25dc0 65 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  en database file
25dd0 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 45 52  , then SQLITE_ER
25de0 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ROR is returned.
25df0 20 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20    This error.** 
25e00 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65  code is not reme
25e10 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20  mbered and will 
25e20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20  not be recalled 
25e30 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  by [sqlite3_errc
25e40 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  ode()].** or [sq
25e50 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
25e60 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
25e70 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
25e80 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20 61 6c  thod might.** al
25e90 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  so return SQLITE
25ea0 5f 45 52 52 4f 52 2e 20 20 54 68 65 72 65 20 69  _ERROR.  There i
25eb0 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74  s no way to dist
25ec0 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a  inguish between.
25ed0 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20  ** an incorrect 
25ee0 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53  zDbName and an S
25ef0 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75  QLITE_ERROR retu
25f00 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65  rn from the unde
25f10 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43  rlying.** xFileC
25f20 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 0a 2a  ontrol method..*
25f30 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
25f40 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
25f50 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74 20 73  KSTATE].*/.int s
25f60 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
25f70 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  rol(sqlite3*, co
25f80 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
25f90 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 2a  e, int op, void*
25fa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 74  );../*.** Undo t
25fb0 68 65 20 68 61 63 6b 20 74 68 61 74 20 63 6f 6e  he hack that con
25fc0 76 65 72 74 73 20 66 6c 6f 61 74 69 6e 67 20 70  verts floating p
25fd0 6f 69 6e 74 20 74 79 70 65 73 20 74 6f 20 69 6e  oint types to in
25fe0 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75 69  teger for.** bui
25ff0 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f 72  lds on processor
26000 73 20 77 69 74 68 6f 75 74 20 66 6c 6f 61 74 69  s without floati
26010 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
26020 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
26030 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
26040 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20 64  _POINT.# undef d
26050 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23 69  ouble.#endif..#i
26060 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73  fdef __cplusplus
26070 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74 68  .}  /* End of th
26080 65 20 27 65 78 74 65 72 6e 20 22 43 22 27 20 62  e 'extern "C"' b
26090 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 23  lock */.#endif.#
260a0 65 6e 64 69 66 0a                                endif.