/ Hex Artifact Content
Login

Artifact 1064c85778f68f501ae91b46cd997084a31e0829:


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 33 30 38 20 32 30 30 38 2f  in,v 1.308 2008/
05f0: 30 34 2f 32 34 20 30 38 3a 35 36 3a 35 34 20 64  04/24 08:56:54 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 20 7b 46 31 30 30 31 30 7d 0a  umbers {F10010}.
0850: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
0860: 5f 56 45 52 53 49 4f 4e 20 61 6e 64 20 53 51 4c  _VERSION and SQL
0870: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0880: 45 52 20 23 64 65 66 69 6e 65 73 20 69 6e 0a 2a  ER #defines in.*
0890: 2a 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20  * the sqlite3.h 
08a0: 66 69 6c 65 20 73 70 65 63 69 66 79 20 74 68 65  file specify the
08b0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
08c0: 74 65 20 77 69 74 68 20 77 68 69 63 68 0a 2a 2a  te with which.**
08d0: 20 74 68 61 74 20 68 65 61 64 65 72 20 66 69 6c   that header fil
08e0: 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e  e is associated.
08f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 76 65 72 73  .**.** The "vers
0900: 69 6f 6e 22 20 6f 66 20 53 51 4c 69 74 65 20 69  ion" of SQLite i
0910: 73 20 61 20 73 74 72 69 6e 67 20 6f 66 20 74 68  s a string of th
0920: 65 20 66 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a  e form "X.Y.Z"..
0930: 2a 2a 20 54 68 65 20 70 68 72 61 73 65 20 22 61  ** The phrase "a
0940: 6c 70 68 61 22 20 6f 72 20 22 62 65 74 61 22 20  lpha" or "beta" 
0950: 6d 69 67 68 74 20 62 65 20 61 70 70 65 6e 64 65  might be appende
0960: 64 20 61 66 74 65 72 20 74 68 65 20 5a 2e 0a 2a  d after the Z..*
0970: 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73  * The X value is
0980: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0990: 75 6d 62 65 72 20 61 6c 77 61 79 73 20 33 20 69  umber always 3 i
09a0: 6e 20 53 51 4c 69 74 65 33 2e 0a 2a 2a 20 54 68  n SQLite3..** Th
09b0: 65 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63  e X value only c
09c0: 68 61 6e 67 65 73 20 77 68 65 6e 20 20 62 61 63  hanges when  bac
09d0: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
09e0: 6c 69 74 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65  lity is.** broke
09f0: 6e 20 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20  n and we intend 
0a00: 74 6f 20 6e 65 76 65 72 20 62 72 65 61 6b 0a 2a  to never break.*
0a10: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
0a20: 61 74 69 62 69 6c 69 74 79 2e 20 20 54 68 65 20  atibility.  The 
0a30: 59 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6d  Y value is the m
0a40: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 0a 2a 2a 20  inor version.** 
0a50: 6e 75 6d 62 65 72 20 61 6e 64 20 6f 6e 6c 79 20  number and only 
0a60: 63 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20  changes when.** 
0a70: 74 68 65 72 65 20 61 72 65 20 6d 61 6a 6f 72 20  there are major 
0a80: 66 65 61 74 75 72 65 20 65 6e 68 61 6e 63 65 6d  feature enhancem
0a90: 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 66 6f  ents that are fo
0aa0: 72 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c  rwards compatibl
0ab0: 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 62 61 63  e.** but not bac
0ac0: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c  kwards compatibl
0ad0: 65 2e 20 20 54 68 65 20 5a 20 76 61 6c 75 65 20  e.  The Z value 
0ae0: 69 73 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  is release numbe
0af0: 72 0a 2a 2a 20 61 6e 64 20 69 73 20 69 6e 63 72  r.** and is incr
0b00: 65 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20  emented with.** 
0b10: 65 61 63 68 20 72 65 6c 65 61 73 65 20 62 75 74  each release but
0b20: 20 72 65 73 65 74 73 20 62 61 63 6b 20 74 6f 20   resets back to 
0b30: 30 20 77 68 65 6e 20 59 20 69 73 20 69 6e 63 72  0 when Y is incr
0b40: 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  emented..**.** S
0b50: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
0b60: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20  3_libversion()] 
0b70: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  and [sqlite3_lib
0b80: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
0b90: 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
0ba0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30  NTS:.**.** {F100
0bb0: 31 31 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56  11} The SQLITE_V
0bc0: 45 52 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69  ERSION #define i
0bd0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20  n the sqlite3.h 
0be0: 68 65 61 64 65 72 20 66 69 6c 65 0a 2a 2a 20 20  header file.**  
0bf0: 20 20 20 20 20 20 20 20 65 76 61 6c 75 61 74 65          evaluate
0c00: 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  s to a string li
0c10: 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68  teral that is th
0c20: 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  e SQLite version
0c30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
0c40: 68 20 77 68 69 63 68 20 74 68 65 20 68 65 61 64  h which the head
0c50: 65 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63  er file is assoc
0c60: 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  iated..**.** {F1
0c70: 30 30 31 34 7d 20 54 68 65 20 53 51 4c 49 54 45  0014} The SQLITE
0c80: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0c90: 23 64 65 66 69 6e 65 20 72 65 73 6f 6c 76 65 73  #define resolves
0ca0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   to an integer.*
0cb0: 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
0cc0: 74 68 65 20 76 61 6c 75 65 20 20 28 58 2a 31 30  the value  (X*10
0cd0: 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b  00000 + Y*1000 +
0ce0: 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20   Z) where X, Y, 
0cf0: 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
0d00: 5a 20 61 72 65 20 74 68 65 20 6d 61 6a 6f 72 20  Z are the major 
0d10: 76 65 72 73 69 6f 6e 2c 20 6d 69 6e 6f 72 20 76  version, minor v
0d20: 65 72 73 69 6f 6e 2c 20 61 6e 64 20 72 65 6c 65  ersion, and rele
0d30: 61 73 65 20 6e 75 6d 62 65 72 2e 0a 2a 2f 0a 23  ase number..*/.#
0d40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0d50: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 20 22 2d  RSION         "-
0d60: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
0d70: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
0d80: 4e 55 4d 42 45 52 20 20 2d 2d 56 45 52 53 49 4f  NUMBER  --VERSIO
0d90: 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a  N-NUMBER--../*.*
0da0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
0db0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
0dc0: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 46 31  sion Numbers {F1
0dd0: 30 30 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  0020}.** KEYWORD
0de0: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
0df0: 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  on.**.** These f
0e00: 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 65 20  eatures provide 
0e10: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
0e20: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c  tion as the [SQL
0e30: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20  ITE_VERSION].** 
0e40: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  and [SQLITE_VERS
0e50: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66  ION_NUMBER] #def
0e60: 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64  ines in the head
0e70: 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 73 6f  er, but are asso
0e80: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
0e90: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
0ea0: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
0eb0: 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73   file.  Cautious
0ec0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
0ed0: 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20  ht.** include a 
0ee0: 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 61  check in their a
0ef0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 65  pplication to ve
0f00: 72 69 66 79 20 74 68 61 74 20 0a 2a 2a 20 73 71  rify that .** sq
0f10: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f20: 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73  _number() always
0f30: 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
0f40: 75 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56  ue .** [SQLITE_V
0f50: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a  ERSION_NUMBER]..
0f60: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
0f70: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
0f80: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
0f90: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
0fa0: 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e  tion as is.** in
0fb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72   the sqlite3_ver
0fc0: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f  sion[] string co
0fd0: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e  nstant.  The fun
0fe0: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
0ff0: 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20  d.** for use in 
1000: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1010: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1020: 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63 74 20  not have direct 
1030: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
1040: 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  .** constants wi
1050: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a  thin the DLL..**
1060: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1070: 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32 31 7d 20 54  **.** {F10021} T
1080: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  he [sqlite3_libv
1090: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d  ersion_number()]
10a0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
10b0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  ns an integer.**
10c0: 20 20 20 20 20 20 20 20 20 20 65 71 75 61 6c 20            equal 
10d0: 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  to [SQLITE_VERSI
10e0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 0a 2a 2a 0a  ON_NUMBER]. .**.
10f0: 2a 2a 20 7b 46 31 30 30 32 32 7d 20 54 68 65 20  ** {F10022} The 
1100: 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e  [sqlite3_version
1110: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1120: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
1130: 65 78 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ext of the.**   
1140: 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 56         [SQLITE_V
1150: 45 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67 2e 20  ERSION] string. 
1160: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32 33 7d 20  .**.** {F10023} 
1170: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  The [sqlite3_lib
1180: 76 65 72 73 69 6f 6e 28 29 5d 20 66 75 6e 63 74  version()] funct
1190: 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ion returns.**  
11a0: 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65          a pointe
11b0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
11c0: 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e  3_version] strin
11d0: 67 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53  g constant..*/.S
11e0: 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e  QLITE_EXTERN con
11f0: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f  st char sqlite3_
1200: 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74  version[];.const
1210: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c   char *sqlite3_l
1220: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b  ibversion(void);
1230: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62  .int sqlite3_lib
1240: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
1250: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
1260: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1270: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1280: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 20  y Is Threadsafe 
1290: 7b 46 31 30 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 53  {F10100}.**.** S
12a0: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
12b0: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
12c0: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
12d0: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 49  When.** the SQLI
12e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 43 20  TE_THREADSAFE C 
12f0: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1300: 72 6f 20 69 73 20 74 72 75 65 2c 20 6d 75 74 65  ro is true, mute
1310: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1320: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1330: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1340: 65 6e 20 74 68 61 74 20 6d 61 63 72 6f 20 69 73  en that macro is
1350: 20 66 61 6c 73 65 2c 0a 2a 2a 20 74 68 65 20 6d   false,.** the m
1360: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
1370: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
1380: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
1390: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
13a0: 73 65 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 6d  se SQLite from m
13b0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
13c0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ead..**.** There
13d0: 20 69 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65   is a measurable
13e0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
13f0: 61 6c 74 79 20 66 6f 72 20 65 6e 61 62 6c 69 6e  alty for enablin
1400: 67 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 20 53 6f  g mutexes..** So
1410: 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20   if speed is of 
1420: 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63  utmost importanc
1430: 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73  e, it makes sens
1440: 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20  e to disable.** 
1450: 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75  the mutexes.  Bu
1460: 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61  t for maximum sa
1470: 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68  fety, mutexes sh
1480: 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e  ould be enabled.
1490: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
14a0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
14b0: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
14c0: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
14d0: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
14e0: 62 65 20 75 73 65 64 20 62 79 20 61 20 70 72 6f  be used by a pro
14f0: 67 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72  gram to make sur
1500: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
1510: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
1520: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
1530: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
1540: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
1550: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
1560: 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 49 54  ing of the SQLIT
1570: 45 5f 54 48 52 45 41 44 53 41 46 45 20 6d 61 63  E_THREADSAFE mac
1580: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ro..**.** INVARI
1590: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ANTS:.**.** {F10
15a0: 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  101} The [sqlite
15b0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
15c0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
15d0: 20 6e 6f 6e 7a 65 72 6f 20 69 66 0a 2a 2a 20 20   nonzero if.**  
15e0: 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77          SQLite w
15f0: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1600: 20 69 74 73 20 6d 75 74 65 78 65 73 20 65 6e 61   its mutexes ena
1610: 62 6c 65 64 20 6f 72 20 7a 65 72 6f 0a 2a 2a 20  bled or zero.** 
1620: 20 20 20 20 20 20 20 20 20 69 66 20 53 51 4c 69           if SQLi
1630: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1640: 77 69 74 68 20 6d 75 74 65 78 65 73 20 64 69 73  with mutexes dis
1650: 61 62 6c 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  abled..*/.int sq
1660: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1670: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1680: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
1690: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
16a0: 64 6c 65 20 7b 46 31 32 30 30 30 7d 0a 2a 2a 20  dle {F12000}.** 
16b0: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62  KEYWORDS: {datab
16c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 0a  ase connection}.
16d0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
16e0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
16f0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
1700: 79 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  y pointer to an 
1710: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a  instance of the.
1720: 2a 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  ** opaque struct
1730: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
1740: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1750: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1760: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1770: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1780: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
1790: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
17a0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
17b0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
17c0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
17d0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
17e0: 74 72 75 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20  tructors.** and 
17f0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1800: 5d 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63  ] is its destruc
1810: 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20  tor.  There are 
1820: 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72  many other inter
1830: 66 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 61  faces.** (such a
1840: 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1850: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
1860: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1870: 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  on()], and.** [s
1880: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1890: 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62  out()] to name b
18a0: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61  ut three) that a
18b0: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68  re methods on th
18c0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f  is.** object..*/
18d0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
18e0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
18f0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
1900: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
1910: 72 20 54 79 70 65 73 20 7b 46 31 30 32 30 30 7d  r Types {F10200}
1920: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1930: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
1940: 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42  e_uint64.**.** B
1950: 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20  ecause there is 
1960: 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72  no cross-platfor
1970: 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79  m way to specify
1980: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1990: 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20  types.** SQLite 
19a0: 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66  includes typedef
19b0: 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67  s for 64-bit sig
19c0: 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64  ned and unsigned
19d0: 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a   integers..**.**
19e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   The sqlite3_int
19f0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75  64 and sqlite3_u
1a00: 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72  int64 are the pr
1a10: 65 66 65 72 72 65 64 20 74 79 70 65 0a 2a 2a 20  eferred type.** 
1a20: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 20 20 54 68  definitions.  Th
1a30: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
1a40: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
1a50: 20 74 79 70 65 73 20 61 72 65 0a 2a 2a 20 73 75   types are.** su
1a60: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
1a70: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1a80: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
1a90: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1aa0: 2a 20 7b 46 31 30 32 30 31 7d 20 54 68 65 20 5b  * {F10201} The [
1ab0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e  sqlite_int64] an
1ac0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d [sqlite3_int64
1ad0: 5d 20 74 79 70 65 73 20 73 70 65 63 69 66 79 20  ] types specify 
1ae0: 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 36 34  a.**          64
1af0: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1b00: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32  ger..**.** {F102
1b10: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f  02} The [sqlite_
1b20: 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c  uint64] and [sql
1b30: 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70  ite3_uint64] typ
1b40: 65 73 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 20  es specify.**   
1b50: 20 20 20 20 20 20 20 61 20 36 34 2d 62 69 74 20         a 64-bit 
1b60: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
1b70: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
1b80: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  TE_INT64_TYPE.  
1b90: 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49  typedef SQLITE_I
1ba0: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
1bb0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
1bc0: 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54  f unsigned SQLIT
1bd0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
1be0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69  ite_uint64;.#eli
1bf0: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
1c00: 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f  ER) || defined(_
1c10: 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74  _BORLANDC__).  t
1c20: 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73  ypedef __int64 s
1c30: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
1c40: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
1c50: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  __int64 sqlite_u
1c60: 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74  int64;.#else.  t
1c70: 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67  ypedef long long
1c80: 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36   int sqlite_int6
1c90: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
1ca0: 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20  igned long long 
1cb0: 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  int sqlite_uint6
1cc0: 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65  4;.#endif.typede
1cd0: 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  f sqlite_int64 s
1ce0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79  qlite3_int64;.ty
1cf0: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e  pedef sqlite_uin
1d00: 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  t64 sqlite3_uint
1d10: 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f  64;../*.** If co
1d20: 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72  mpiling for a pr
1d30: 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63  ocessor that lac
1d40: 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ks floating poin
1d50: 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75  t support,.** su
1d60: 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72  bstitute integer
1d70: 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f   for floating-po
1d80: 69 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  int.*/.#ifdef SQ
1d90: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
1da0: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e  NG_POINT.# defin
1db0: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  e double sqlite3
1dc0: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f  _int64.#endif../
1dd0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1de0: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73  losing A Databas
1df0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31  e Connection {F1
1e00: 32 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2010}.**.** This
1e10: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
1e20: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
1e30: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1e40: 65 63 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 70 70  ect.  .**.** App
1e50: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
1e60: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1e70: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
1e80: 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  ll.** [prepared 
1e90: 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 0a  statements] and.
1ea0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
1eb0: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20  _close | close] 
1ec0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  all [sqlite3_blo
1ed0: 62 20 7c 20 42 4c 4f 42 73 5d 20 0a 2a 2a 20 61  b | BLOBs] .** a
1ee0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1ef0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1f00: 65 63 74 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20  ect prior.** to 
1f10: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c  attempting to cl
1f20: 6f 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ose the [sqlite3
1f30: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
1f40: 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70 65  <todo>What happe
1f50: 6e 73 20 74 6f 20 70 65 6e 64 69 6e 67 20 74 72  ns to pending tr
1f60: 61 6e 73 61 63 74 69 6f 6e 73 3f 20 20 41 72 65  ansactions?  Are
1f70: 20 74 68 65 79 0a 2a 2a 20 72 6f 6c 6c 65 64 20   they.** rolled 
1f80: 62 61 63 6b 2c 20 6f 72 20 61 62 61 6e 64 6f 6e  back, or abandon
1f90: 65 64 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ed?</todo>.**.**
1fa0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1fb0: 2a 2a 20 7b 46 31 32 30 31 31 7d 20 54 68 65 20  ** {F12011} The 
1fc0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1fd0: 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74  ] interface dest
1fe0: 72 6f 79 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  roys an [sqlite3
1ff0: 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20  ] object.**     
2000: 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62       allocated b
2010: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
2020: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2030: 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2040: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2050: 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
2060: 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
2070: 2a 20 7b 46 31 32 30 31 32 7d 20 54 68 65 20 5b  * {F12012} The [
2080: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2090: 20 66 75 6e 63 74 69 6f 6e 20 72 65 6c 65 61 73   function releas
20a0: 65 73 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 75 73  es all memory us
20b0: 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
20c0: 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e        connection
20d0: 20 61 6e 64 20 63 6c 6f 73 65 73 20 61 6c 6c 20   and closes all 
20e0: 6f 70 65 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a  open files..**.*
20f0: 2a 20 7b 46 31 32 30 31 33 7d 20 49 66 20 74 68  * {F12013} If th
2100: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2110: 63 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 0a 2a  ction contains.*
2120: 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2130: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2140: 20 74 68 61 74 20 68 61 76 65 20 6e 6f 74 20 62   that have not b
2150: 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  een.**          
2160: 66 69 6e 61 6c 69 7a 65 64 20 62 79 20 5b 73 71  finalized by [sq
2170: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2180: 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ], then [sqlite3
2190: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 20 20 20  _close()].**    
21a0: 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 5b 53        returns [S
21b0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
21c0: 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 6e 65  leaves the conne
21d0: 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a  ction open..**.*
21e0: 2a 20 7b 46 31 32 30 31 34 7d 20 47 69 76 69 6e  * {F12014} Givin
21f0: 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  g sqlite3_close(
2200: 29 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ) a NULL pointer
2210: 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
2220: 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  o-op..**.** LIMI
2230: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
2240: 55 31 32 30 31 35 7d 20 54 68 65 20 70 61 72 61  U12015} The para
2250: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2260: 33 5f 63 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20  3_close()] must 
2270: 62 65 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  be an [sqlite3] 
2280: 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20  object.**       
2290: 20 20 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69     pointer previ
22a0: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
22b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
22c0: 6e 28 29 5d 20 6f 72 20 74 68 65 20 0a 2a 2a 20  n()] or the .** 
22d0: 20 20 20 20 20 20 20 20 20 65 71 75 69 76 61 6c           equival
22e0: 65 6e 74 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  ent, or NULL..**
22f0: 0a 2a 2a 20 7b 55 31 32 30 31 36 7d 20 54 68 65  .** {U12016} The
2300: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2310: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
2320: 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
2330: 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  en previously.**
2340: 20 20 20 20 20 20 20 20 20 20 63 6c 6f 73 65 64            closed
2350: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2360: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2370: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2380: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
2390: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
23a0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
23b0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
23c0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
23d0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
23e0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
23f0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2400: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2410: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2420: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2430: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2440: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2450: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2460: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2470: 65 72 66 61 63 65 20 7b 46 31 32 31 30 30 7d 0a  erface {F12100}.
2480: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2490: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
24a0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
24b0: 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e  nt way of runnin
24c0: 67 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  g.** one or more
24d0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
24e0: 77 69 74 68 6f 75 74 20 61 20 6c 6f 74 20 6f 66  without a lot of
24f0: 20 43 20 63 6f 64 65 2e 20 20 54 68 65 0a 2a 2a   C code.  The.**
2500: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2510: 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61 73  are passed in as
2520: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2530: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
2540: 74 65 33 5f 65 78 65 63 28 29 2e 20 20 54 68 65  te3_exec().  The
2550: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2560: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2570: 20 6f 6e 65 0a 2a 2a 20 75 6e 74 69 6c 20 65 69   one.** until ei
2580: 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72  ther an error or
2590: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
25a0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6f 72 0a   encountered or.
25b0: 2a 2a 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72  ** until they ar
25c0: 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65  e all done.  The
25d0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
25e0: 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 0a 2a 2a  s an optional.**
25f0: 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69   callback that i
2600: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66  s invoked once f
2610: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61  or each row of a
2620: 6e 79 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ny query results
2630: 0a 2a 2a 20 70 72 6f 64 75 63 65 64 20 62 79 20  .** produced by 
2640: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2650: 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72  ts.  The 5th par
2660: 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65  ameter tells whe
2670: 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61  re.** to write a
2680: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
2690: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
26a0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
26b0: 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
26c0: 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66  nted in terms of
26d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
26e0: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
26f0: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
2700: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2710: 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  ize()]..** The s
2720: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f  qlite3_exec() ro
2730: 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69  utine does nothi
2740: 6e 67 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  ng that cannot b
2750: 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71  e done.** by [sq
2760: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2770: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2780: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2790: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
27a0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27b0: 65 78 65 63 28 29 20 69 73 20 6a 75 73 74 20 61  exec() is just a
27c0: 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 72 61 70   convenient wrap
27d0: 70 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  per..**.** INVAR
27e0: 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46  IANTS:.** .** {F
27f0: 31 32 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  12101} The [sqli
2800: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 6e 74 65  te3_exec()] inte
2810: 72 66 61 63 65 20 65 76 61 6c 75 61 74 65 73 20  rface evaluates 
2820: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
2830: 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  -8.**          e
2840: 6e 63 6f 64 65 64 2c 20 73 65 6d 69 63 6f 6c 6f  ncoded, semicolo
2850: 6e 2d 73 65 70 61 72 61 74 65 64 2c 20 53 51 4c  n-separated, SQL
2860: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
2870: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  he.**          z
2880: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
2890: 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
28a0: 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 69   parameter withi
28b0: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
28c0: 20 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65    context of the
28d0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
28e0: 74 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 31  t given in the 1
28f0: 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
2900: 0a 2a 2a 20 7b 46 31 32 31 30 34 7d 20 54 68 65  .** {F12104} The
2910: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2920: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2930: 5d 20 69 73 20 53 51 4c 49 54 45 5f 4f 4b 20 69  ] is SQLITE_OK i
2940: 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  f all.**        
2950: 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73    SQL statements
2960: 20 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c   run successfull
2970: 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 35  y..**.** {F12105
2980: 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
2990: 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  ue of [sqlite3_e
29a0: 78 65 63 28 29 5d 20 69 73 20 61 6e 20 61 70 70  xec()] is an app
29b0: 72 6f 70 72 69 61 74 65 20 0a 2a 2a 20 20 20 20  ropriate .**    
29c0: 20 20 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 65        non-zero e
29d0: 72 72 6f 72 20 63 6f 64 65 20 69 66 20 61 6e 79  rror code if any
29e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
29f0: 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ails..**.** {F12
2a00: 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d  107} If one or m
2a10: 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ore of the SQL s
2a20: 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64  tatements handed
2a30: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
2a40: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
2a50: 20 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20   return results 
2a60: 61 6e 64 20 74 68 65 20 33 72 64 20 70 61 72 61  and the 3rd para
2a70: 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  meter is not NUL
2a80: 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  L, then.**      
2a90: 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b      the callback
2aa0: 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66   function specif
2ab0: 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70  ied by the 3rd p
2ac0: 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20  arameter is.**  
2ad0: 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20          invoked 
2ae0: 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f  once for each ro
2af0: 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a  w of result..**.
2b00: 2a 2a 20 7b 46 31 32 31 31 30 7d 20 49 66 20 74  ** {F12110} If t
2b10: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
2b20: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76  rns a non-zero v
2b30: 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74  alue then [sqlit
2b40: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20  e3_exec()].**   
2b50: 20 20 20 20 20 20 20 77 69 6c 6c 20 61 62 6f 72         will abor
2b60: 74 65 64 20 74 68 65 20 53 51 4c 20 73 74 61 74  ted the SQL stat
2b70: 65 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72 72  ement it is curr
2b80: 65 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e 67  ently evaluating
2b90: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6b  ,.**          sk
2ba0: 69 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  ip all subsequen
2bb0: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
2bc0: 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  , and return [SQ
2bd0: 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20  LITE_ABORT]..** 
2be0: 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57           <todo>W
2bf0: 68 61 74 20 68 61 70 70 65 6e 73 20 74 6f 20 2a  hat happens to *
2c00: 65 72 72 6d 73 67 20 68 65 72 65 3f 20 20 44 6f  errmsg here?  Do
2c10: 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  es the result co
2c20: 64 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  de for.**       
2c30: 20 20 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f     sqlite3_errco
2c40: 64 65 28 29 20 67 65 74 20 73 65 74 3f 3c 2f 74  de() get set?</t
2c50: 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  odo>.**.** {F121
2c60: 31 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  13} The [sqlite3
2c70: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
2c80: 20 77 69 6c 6c 20 70 61 73 73 20 69 74 73 20 34   will pass its 4
2c90: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 72  th parameter thr
2ca0: 6f 75 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  ough.**         
2cb0: 20 61 73 20 74 68 65 20 31 73 74 20 70 61 72 61   as the 1st para
2cc0: 6d 65 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c  meter of the cal
2cd0: 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lback..**.** {F1
2ce0: 32 31 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  2116} The [sqlit
2cf0: 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69  e3_exec()] routi
2d00: 6e 65 20 73 65 74 73 20 74 68 65 20 32 6e 64 20  ne sets the 2nd 
2d10: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73  parameter of its
2d20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
2d30: 6c 62 61 63 6b 20 74 6f 20 62 65 20 74 68 65 20  lback to be the 
2d40: 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2d50: 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  s in the current
2d60: 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20   row of.**      
2d70: 20 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a      result..**.*
2d80: 2a 20 7b 46 31 32 31 31 39 7d 20 54 68 65 20 5b  * {F12119} The [
2d90: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
2da0: 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68 65  routine sets the
2db0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f   3rd parameter o
2dc0: 66 20 69 74 73 20 0a 2a 2a 20 20 20 20 20 20 20  f its .**       
2dd0: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
2de0: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
2df0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
2e00: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
2e10: 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 73            values
2e20: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
2e30: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2e40: 72 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20 61  result set row a
2e50: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  s.**          ob
2e60: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2e70: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e80: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ()]..**.** {F121
2e90: 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  22} The [sqlite3
2ea0: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
2eb0: 20 73 65 74 73 20 74 68 65 20 34 74 68 20 70 61   sets the 4th pa
2ec0: 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a  rameter of its.*
2ed0: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
2ee0: 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72  ack to be an arr
2ef0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
2f00: 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e  o strings holdin
2f10: 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  g the.**        
2f20: 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73 75 6c    names of resul
2f30: 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74  t columns as obt
2f40: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2f50: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2f60: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32  )]..**.** {F1212
2f70: 35 7d 20 49 66 20 74 68 65 20 33 72 64 20 70 61  5} If the 3rd pa
2f80: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2f90: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 4e  te3_exec()] is N
2fa0: 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  ULL then.**     
2fb0: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78       [sqlite3_ex
2fc0: 65 63 28 29 5d 20 6e 65 76 65 72 20 69 6e 76 6f  ec()] never invo
2fd0: 6b 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 2e 20  kes a callback. 
2fe0: 20 41 6c 6c 20 71 75 65 72 79 0a 2a 2a 20 20 20   All query.**   
2ff0: 20 20 20 20 20 20 20 72 65 73 75 6c 74 73 20 61         results a
3000: 72 65 20 73 69 6c 65 6e 74 6c 79 20 64 69 73 63  re silently disc
3010: 61 72 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  arded..**.** {F1
3020: 32 31 32 38 7d 20 49 66 20 61 6e 20 65 72 72 6f  2128} If an erro
3030: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70  r occurs while p
3040: 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61  arsing or evalua
3050: 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65 20  ting any of the 
3060: 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  SQL.**          
3070: 73 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65  statements hande
3080: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  d to [sqlite3_ex
3090: 65 63 28 29 5d 20 74 68 65 6e 20 5b 73 71 6c 69  ec()] then [sqli
30a0: 74 65 33 5f 65 78 65 63 28 29 5d 20 77 69 6c 6c  te3_exec()] will
30b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
30c0: 75 72 6e 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  urn an [error co
30d0: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
30e0: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
30f0: 2a 20 7b 46 31 32 31 33 31 7d 20 49 66 20 61 6e  * {F12131} If an
3100: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3110: 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 20 65  ile parsing or e
3120: 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f 66  valuating any of
3130: 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20   the SQL.**     
3140: 20 20 20 20 20 68 61 6e 64 65 64 20 74 6f 20 5b       handed to [
3150: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3160: 61 6e 64 20 69 66 20 74 68 65 20 35 74 68 20 70  and if the 5th p
3170: 61 72 61 6d 65 74 65 72 20 28 65 72 72 6d 73 67  arameter (errmsg
3180: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  ).**          to
3190: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
31a0: 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ] is not NULL, t
31b0: 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  hen an error mes
31c0: 73 61 67 65 20 69 73 0a 2a 2a 20 20 20 20 20 20  sage is.**      
31d0: 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 75 73      allocated us
31e0: 69 6e 67 20 74 68 65 20 65 71 75 69 76 61 6c 65  ing the equivale
31f0: 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  nt of [sqlite3_m
3200: 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 0a 2a 2a  printf()] and.**
3210: 20 20 20 20 20 20 20 20 20 20 2a 65 72 72 6d 73            *errms
3220: 67 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  g is made to poi
3230: 6e 74 20 74 6f 20 74 68 61 74 20 6d 65 73 73 61  nt to that messa
3240: 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33  ge..**.** {F1213
3250: 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
3260: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
3270: 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
3280: 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
3290: 20 20 20 20 20 20 20 20 20 2a 65 72 72 6d 73 67           *errmsg
32a0: 20 69 66 20 65 72 72 6d 73 67 20 69 73 20 4e 55   if errmsg is NU
32b0: 4c 4c 20 6f 72 20 69 66 20 74 68 65 72 65 20 61  LL or if there a
32c0: 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a  re no errors..**
32d0: 0a 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54 68 65  .** {F12137} The
32e0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
32f0: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20  ] function sets 
3300: 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61  the error code a
3310: 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20  nd message.**   
3320: 20 20 20 20 20 20 20 61 63 63 65 73 73 69 62 6c         accessibl
3330: 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65  e via [sqlite3_e
3340: 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69  rrcode()], [sqli
3350: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61  te3_errmsg()], a
3360: 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
3370: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
3380: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  ()]..**.** LIMIT
3390: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
33a0: 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 74  12141} The first
33b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
33c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d  qlite3_exec()] m
33d0: 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20  ust be an valid 
33e0: 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20  and open.**     
33f0: 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
3400: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
3410: 2a 20 7b 55 31 32 31 34 32 7d 20 54 68 65 20 64  * {U12142} The d
3420: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3430: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63  on must not be c
3440: 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 20  losed while.**  
3450: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
3460: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
3470: 69 6e 67 2e 0a 2a 2a 20 0a 2a 2a 20 7b 55 31 32  ing..** .** {U12
3480: 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  143} The calling
3490: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 68 6f   function is sho
34a0: 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33  uld use [sqlite3
34b0: 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65  _free()] to free
34c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
34d0: 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72   memory that *er
34e0: 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69  rmsg is left poi
34f0: 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68  nting at once th
3500: 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20  e error.**      
3510: 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e      message is n
3520: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3530: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 35 7d 20  .**.** {U12145} 
3540: 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  The SQL statemen
3550: 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e  t text in the 2n
3560: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
3570: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a  sqlite3_exec()].
3580: 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73 74  **          must
3590: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
35a0: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
35b0: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
35c0: 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
35d0: 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69  te3_exec(.  sqli
35e0: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
35f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3600: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
3610: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
3620: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c  const char *sql,
3630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3640: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
3650: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 74 65 64  L to be evaluted
3660: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
3670: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
3680: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
3690: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
36a0: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
36b0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
36c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36d0: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
36e0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
36f0: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
3700: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
3710: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3720: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
3730: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
3740: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3750: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  F: Result Codes 
3760: 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 4b 45 59 57  {F10210}.** KEYW
3770: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3780: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3790: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ror codes}.**.**
37a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
37b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
37c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
37d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
37e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
37f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
3800: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72  cates success or
3810: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
3820: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
3830: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
3840: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3850: 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  odes].*/.#define
3860: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
3870: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
3880: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
3890: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
38a0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
38b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
38c0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
38d0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
38e0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
38f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3900: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
3910: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
3920: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
3930: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
3940: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
3950: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
3960: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
3970: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
3980: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
3990: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
39a0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
39b0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
39c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
39d0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
39e0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
39f0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
3a00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3a10: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
3a20: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
3a30: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
3a40: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
3a50: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
3a60: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
3a70: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
3a80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3a90: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
3aa0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
3ab0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
3ac0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
3ad0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
3ae0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
3af0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
3b00: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
3b10: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
3b20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3b30: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
3b40: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
3b50: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
3b60: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
3b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
3b80: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
3b90: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
3ba0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
3bb0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3bc0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
3bd0: 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   12   /* NOT USE
3be0: 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f  D. Table or reco
3bf0: 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a  rd not found */.
3c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
3c10: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
3c20: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
3c30: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
3c40: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
3c50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
3c60: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
3c70: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
3c80: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
3c90: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
3ca0: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
3cb0: 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53    15   /* NOT US
3cc0: 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63  ED. Database loc
3cd0: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
3ce0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3cf0: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
3d00: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
3d10: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
3d20: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
3d30: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
3d40: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
3d50: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
3d60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
3d70: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
3d80: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
3d90: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
3da0: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
3db0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
3dc0: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
3dd0: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
3de0: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
3df0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
3e00: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
3e10: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
3e20: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
3e30: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
3e40: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
3e50: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
3e60: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
3e70: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
3e80: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
3e90: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
3ea0: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
3eb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3ec0: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
3ed0: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
3ee0: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
3ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
3f00: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
3f10: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
3f20: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
3f30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3f40: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
3f50: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
3f60: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3f70: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
3f80: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
3f90: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
3fa0: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
3fb0: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
3fc0: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
3fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3fe0: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
3ff0: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4000: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4010: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4030: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4040: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4050: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4060: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4070: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4080: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4090: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
40a0: 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 32  ult Codes {F1022
40b0: 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
40c0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
40d0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
40e0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
40f0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4100: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4110: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  }.**.** In its d
4120: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
4130: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
4140: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
4150: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
4160: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  er.** [SQLITE_OK
4170: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4180: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4190: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
41a0: 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66   that.** many of
41b0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
41c0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 72  des are too cour
41d0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
41e0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
41f0: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4200: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4210: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4220: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4230: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4240: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4250: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4260: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4270: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4280: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4290: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
42a0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
42b0: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
42c0: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
42d0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
42e0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
42f0: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
4300: 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62  t codes are enab
4310: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
4320: 2a 2a 20 66 6f 72 20 65 61 63 68 20 64 61 74 61  ** for each data
4330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4340: 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
4350: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4360: 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 41  lt_codes()].** A
4370: 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20  PI..** .** Some 
4380: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  of the available
4390: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
43a0: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65   codes are liste
43b0: 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d  d here..** One m
43c0: 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75  ay expect the nu
43d0: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64  mber of extended
43e0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69   result codes wi
43f0: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20  ll be expand.** 
4400: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74  over time.  Soft
4410: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65  ware that uses e
4420: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4430: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65  odes should expe
4440: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77  ct.** to see new
4450: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e   result codes in
4460: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
4470: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4480: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
4490: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
44a0: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
44b0: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
44c0: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
44d0: 79 20 7a 65 72 6f 2e 0a 2a 2a 20 0a 2a 2a 20 49  y zero..** .** I
44e0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
44f0: 20 7b 46 31 30 32 32 33 7d 20 54 68 65 20 73 79   {F10223} The sy
4500: 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20  mbolic name for 
4510: 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  an extended resu
4520: 6c 74 20 63 6f 64 65 20 61 6c 77 61 79 73 20 63  lt code always c
4530: 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
4540: 20 20 20 20 61 20 72 65 6c 61 74 65 64 20 70 72      a related pr
4550: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
4560: 65 20 61 73 20 61 20 70 72 65 66 69 78 2e 0a 2a  e as a prefix..*
4570: 2a 0a 2a 2a 20 7b 46 31 30 32 32 34 7d 20 50 72  *.** {F10224} Pr
4580: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
4590: 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20  e names contain 
45a0: 61 20 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61  a single "_" cha
45b0: 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  racter..**.** {F
45c0: 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20  10225} Extended 
45d0: 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65  result code name
45e0: 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72  s contain two or
45f0: 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63   more "_" charac
4600: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ters..**.** {F10
4610: 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63  226} The numeric
4620: 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74   value of an ext
4630: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4640: 65 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  e contains the.*
4650: 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 65 72  *          numer
4660: 69 63 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20  ic value of its 
4670: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72  corresponding pr
4680: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
4690: 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e in.**         
46a0: 20 69 74 73 20 6c 65 61 73 74 20 73 69 67 6e 69   its least signi
46b0: 66 69 63 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a  ficant 8 bits..*
46c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46d0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
46e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
46f0: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
4700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4710: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
4720: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4730: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
4740: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
4750: 54 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  TE         (SQLI
4760: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4770: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4780: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4790: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
47a0: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
47b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
47c0: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
47d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
47e0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
47f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
4800: 55 4e 43 41 54 45 20 20 20 20 20 20 28 53 51 4c  UNCATE      (SQL
4810: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
4820: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4830: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
4840: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4850: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4870: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4880: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4890: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
48a0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
48b0: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51  DLOCK        (SQ
48c0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
48d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
48e0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
48f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4900: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
4910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4920: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
4930: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4940: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4960: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4970: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4980: 28 31 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20  (12<<8))../*.** 
4990: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
49a0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
49b0: 65 72 61 74 69 6f 6e 73 20 7b 46 31 30 32 33 30  erations {F10230
49c0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  }.**.** These bi
49d0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
49e0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
49f0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
4a00: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
4a10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
4a20: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
4a30: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
4a40: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f  ameter to the xO
4a50: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  pen method of th
4a60: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
4a70: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
4a80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4a90: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
4aa0: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
4ab0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4ac0: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
4ad0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
4ae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4af0: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
4b00: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
4b10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4b20: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
4b30: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
4b40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4b50: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
4b60: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
4b70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4b80: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
4b90: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
4ba0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4bb0: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
4bc0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
4bd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4be0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
4bf0: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64     0x00000400.#d
4c00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4c10: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
4c20: 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64     0x00000800.#d
4c30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4c40: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
4c50: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
4c60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4c70: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
4c80: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64     0x00002000.#d
4c90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4ca0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
4cb0: 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f     0x00004000../
4cc0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
4cd0: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
4ce0: 73 74 69 63 73 20 7b 46 31 30 32 34 30 7d 0a 2a  stics {F10240}.*
4cf0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
4d00: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
4d10: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
4d20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
4d30: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
4d40: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
4d50: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
4d60: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
4d70: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
4d80: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
4d90: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
4da0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
4db0: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
4dc0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
4dd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
4de0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
4df0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
4e00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4e10: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
4e20: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
4e30: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
4e40: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
4e50: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4e60: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
4e70: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
4e80: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
4e90: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
4ea0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
4eb0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
4ec0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
4ed0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
4ee0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
4ef0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
4f00: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4f10: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
4f20: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
4f30: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
4f40: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
4f50: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
4f60: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
4f70: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
4f80: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
4f90: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
4fa0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
4fb0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
4fc0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
4fd0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
4fe0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
4ff0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
5000: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
5010: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
5020: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
5030: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
5040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5050: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
5060: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5070: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5080: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
5090: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
50a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
50b0: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
50c0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
50d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
50e0: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
50f0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
5100: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5110: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
5120: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5130: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5140: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
5150: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5160: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5170: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
5180: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5190: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
51a0: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
51b0: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
51c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
51d0: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
51e0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
51f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5200: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
5210: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
5220: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5230: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
5240: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
5250: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
5260: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 46 31 30  king Levels {F10
5270: 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  250}.**.** SQLit
5280: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
5290: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
52a0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
52b0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
52c0: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
52d0: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
52e0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
52f0: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
5300: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5310: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
5320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5330: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
5340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5350: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
5360: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
5370: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
5380: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
5390: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
53a0: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
53b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
53c0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
53d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
53e0: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
53f0: 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b 46 31  n Type Flags {F1
5400: 30 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  0260}.**.** When
5410: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
5420: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
5430: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
5440: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5450: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
5460: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
5470: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
5480: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
5490: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
54a0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
54b0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
54c0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
54d0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
54e0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
54f0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
5500: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
5510: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
5520: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
5530: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
5540: 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20  be flushed. The 
5550: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5560: 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a  AL flag means .*
5570: 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  * to use normal 
5580: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
5590: 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  s. The SQLITE_SY
55a0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61  NC_FULL flag mea
55b0: 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ns .** to use Ma
55c0: 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c  c OS-X style ful
55d0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
55e0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65   fsync()..*/.#de
55f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
5600: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
5610: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
5620: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
5630: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
5640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5650: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
5660: 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a     0x00010.../*.
5670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
5680: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
5690: 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46 31 31 31  ile Handle {F111
56a0: 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  10}.**.** An [sq
56b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
56c0: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
56d0: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
56e0: 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e OS.** interfac
56f0: 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69  e layer.  Indivi
5700: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
5710: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
5720: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
5730: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
5740: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
5750: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
5760: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
5770: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
5780: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
5790: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
57a0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
57b0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
57c0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
57d0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
57e0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
57f0: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
5800: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
5810: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
5820: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
5830: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
5840: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
5850: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
5860: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
5870: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
5880: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
5890: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
58a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
58b0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
58c0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
58d0: 4f 62 6a 65 63 74 20 7b 46 31 31 31 32 30 7d 0a  Object {F11120}.
58e0: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
58f0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
5900: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
5910: 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69  en method contai
5920: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  ns a pointer to.
5930: 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** an instance o
5940: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20 20  f this object.  
5950: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
5960: 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74 68 6f  nes the.** metho
5970: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
5980: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
5990: 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20 74 68  tions against th
59a0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a 0a  e open file..**.
59b0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
59c0: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
59d0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
59e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
59f0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
5a00: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
5a10: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
5a20: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
5a30: 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65 63 6f  c()..*  The seco
5a40: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 6e 0a  nd choice is an.
5a50: 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75  ** OS-X style fu
5a60: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53 51 4c  llsync.  The SQL
5a70: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66 6c  ITE_SYNC_DATA fl
5a80: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
5a90: 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61 74 65  n to.** indicate
5aa0: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
5ab0: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ata of the file 
5ac0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
5ad0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a 2a 2a  e needs to be.**
5ae0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a 2a 20   synced..** .** 
5af0: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
5b00: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
5b10: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
5b20: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
5b30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
5b40: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
5b50: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5b60: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
5b70: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
5b80: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
5b90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
5ba0: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
5bb0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5bc0: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
5bd0: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
5be0: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
5bf0: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
5c00: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
5c10: 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  .  .** The xChec
5c20: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
5c30: 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a 20  method looks.** 
5c40: 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20 64 61  to see if any da
5c50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5c60: 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  n, either in thi
5c70: 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72 20  s.** process or 
5c80: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
5c90: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
5ca0: 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c 0a 2a  g an RESERVED,.*
5cb0: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
5cc0: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
5cd0: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
5ce0: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
5cf0: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
5d00: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 69 66  sts and false if
5d10: 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65   not..** .** The
5d20: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
5d30: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
5d40: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
5d50: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
5d60: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
5d70: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
5d80: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
5d90: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
5da0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
5db0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
5dc0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
5dd0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
5de0: 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74  ent.** is an int
5df0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 20 54  eger opcode.   T
5e00: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
5e10: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
5e20: 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  c pointer which 
5e30: 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
5e40: 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  e a pointer.** t
5e50: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
5e60: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
5e70: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
5e80: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
5e90: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
5ea0: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
5eb0: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
5ec0: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
5ed0: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
5ee0: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
5ef0: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
5f00: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
5f10: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
5f20: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
5f30: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
5f40: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
5f50: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
5f60: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
5f70: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
5f80: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
5f90: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
5fa0: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 6f 70  core reserves op
5fb0: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
5fc0: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
5fd0: 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51 4c 49  use. .** A [SQLI
5fe0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
5ff0: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  TE | list of opc
6000: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
6010: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
6020: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
6030: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
6040: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
6050: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
6060: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20 0a 2a  d use opcodes .*
6070: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
6080: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
6090: 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  licts..**.** The
60a0: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
60b0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
60c0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
60d0: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
60e0: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
60f0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
6100: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
6110: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
6120: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
6130: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
6140: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
6150: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
6160: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
6170: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6180: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
6190: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
61a0: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
61b0: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
61c0: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
61d0: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
61e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
61f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
6200: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6210: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
6220: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6230: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
6240: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6250: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
6260: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6270: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
6280: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6290: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
62a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
62b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
62c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
62d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
62e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
62f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
6300: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6310: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6320: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
6330: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6340: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
6350: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6360: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
6370: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6380: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
6390: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
63a0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
63b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
63c0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
63d0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
63e0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
63f0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6400: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6410: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6420: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
6430: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
6440: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
6450: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6460: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6470: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
6480: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
6490: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
64a0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
64b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
64c0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
64d0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
64e0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
64f0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6500: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6510: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6520: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
6530: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6540: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
6550: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
6560: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
6570: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
6580: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
6590: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
65a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
65b0: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
65c0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
65d0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
65e0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
65f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
6600: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6610: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
6620: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6630: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
6640: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
6650: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
6660: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
6670: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
6680: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
6690: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
66a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
66b0: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
66c0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
66d0: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
66e0: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
66f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
6700: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
6710: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
6720: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
6730: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
6740: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
6750: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
6760: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
6770: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6780: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
6790: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
67a0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
67b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
67c0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
67d0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
67e0: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
67f0: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
6800: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6810: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
6820: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6830: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6840: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
6850: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
6860: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
6870: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
6880: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6890: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
68a0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b  ontrol Opcodes {
68b0: 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F11310}.**.** Th
68c0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
68d0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
68e0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
68f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
6900: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6910: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6920: 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65 20 5b  ect and to the [
6930: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6940: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
6950: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
6960: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
6970: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
6980: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
6990: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
69a0: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
69b0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
69c0: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
69d0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
69e0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
69f0: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
6a00: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
6a10: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6a20: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
6a30: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
6a40: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6a50: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
6a60: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
6a70: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
6a80: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
6a90: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
6aa0: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
6ab0: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
6ac0: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
6ad0: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
6ae0: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
6af0: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
6b00: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  * is defined..*/
6b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b20: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
6b30: 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20         1../*.** 
6b40: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
6b50: 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d 0a  Handle {F17110}.
6b60: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
6b70: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
6b80: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
6b90: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
6ba0: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
6bb0: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
6bc0: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
6bd0: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
6be0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
6bf0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
6c00: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
6c10: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
6c20: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
6c30: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
6c40: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
6c50: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
6c60: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
6c70: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
6c80: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
6c90: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
6ca0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6cb0: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
6cc0: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
6cd0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
6ce0: 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46 31  rface Object {F1
6cf0: 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  1140}.**.** An i
6d00: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6d10: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6d20: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
6d30: 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  ween the.** SQLi
6d40: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
6d50: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
6d60: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
6d70: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
6d80: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
6d90: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
6da0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
6db0: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
6dc0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
6dd0: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
6de0: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
6df0: 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 76   for future.** v
6e00: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
6e10: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
6e20: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
6e30: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
6e40: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
6e50: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
6e60: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a  is increased..**
6e70: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
6e80: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
6e90: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
6ea0: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
6eb0: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
6ec0: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
6ed0: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
6ee0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
6ef0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
6f00: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
6f10: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
6f20: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
6f30: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
6f40: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
6f50: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
6f60: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
6f70: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
6f80: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
6f90: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
6fa0: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
6fb0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
6fc0: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
6fd0: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
6fe0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
6ff0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7000: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7010: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7020: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
7030: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
7040: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
7050: 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20  sqlite3_vfs .** 
7060: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
7070: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
7080: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
7090: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
70a0: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
70b0: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
70c0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
70d0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
70e0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
70f0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
7100: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
7110: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
7120: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
7130: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
7140: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
7150: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
7160: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
7170: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
7180: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
7190: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
71a0: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
71b0: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
71c0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34  es..**.** {F1114
71d0: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  1} SQLite will g
71e0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
71f0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69  e zFilename stri
7200: 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  ng passed to.** 
7210: 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c  xOpen() is a ful
7220: 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65  l pathname as ge
7230: 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c  nerated by xFull
7240: 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a  Pathname() and.*
7250: 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69 6e  * that the strin
7260: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
7270: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
7280: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
7290: 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 4e 44  ** called.  {END
72a0: 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  } So the [sqlite
72b0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72  3_file] can stor
72c0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
72d0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
72e0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
72f0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
7300: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
7310: 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  son..**.** {F111
7320: 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  42} The flags ar
7330: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
7340: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
7350: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
7360: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7370: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
7380: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
7390: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
73a0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
73b0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
73c0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
73d0: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
73e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
73f0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
7400: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
7410: 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78  ]. {END}.** If x
7420: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
7430: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
7440: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
7450: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
7460: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
7470: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
7480: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
7490: 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20  Flags may be.** 
74a0: 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31  set..** .** {F11
74b0: 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  143} SQLite will
74c0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
74d0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
74e0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
74f0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
7500: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
7510: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
7520: 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  d:.** .** <ul>.*
7530: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7540: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
7550: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7560: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
7570: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7580: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
7590: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
75a0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
75b0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
75c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
75d0: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
75e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
75f0: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
7600: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7610: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
7620: 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
7630: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
7640: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
7650: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
7660: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
7670: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68  to.** changes th
7680: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
7690: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
76a0: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
76b0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
76c0: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
76d0: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
76e0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
76f0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
7700: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
7710: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
7720: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
7730: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
7740: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
7750: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
7760: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
7770: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
7780: 72 6e 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  rn .** SQLITE_IO
7790: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
77a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
77b0: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
77c0: 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
77d0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
77e0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
77f0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
7800: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
7810: 64 6f 6d 20 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  dom .** order an
7820: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
7830: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
7840: 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53  dingly..** .** S
7850: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
7860: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
7870: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
7880: 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
7890: 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  method:.** .** <
78a0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
78b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
78c0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
78d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
78e0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
78f0: 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35 7d  .** .** {F11145}
7900: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7910: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7920: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
7930: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
7940: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
7950: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46  t is closed.  {F
7960: 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49  11146} The [SQLI
7970: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7980: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
7990: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20  e set for TEMP  
79a0: 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e  databases, journ
79b0: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
79c0: 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46 31  ournals. .** {F1
79d0: 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54  1147} The [SQLIT
79e0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
79f0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
7a00: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
7a10: 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78  opened.** for ex
7a20: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20  clusive access. 
7a30: 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65   This flag is se
7a40: 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20  t for all files 
7a50: 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68  except.** for th
7a60: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
7a70: 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a  file. {END}.** .
7a80: 2a 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 6c  ** {F11148} At l
7a90: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
7aa0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
7ab0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
7ac0: 51 4c 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f 6c  QLite .** to hol
7ad0: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
7ae0: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
7af0: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
7b00: 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ird .** argument
7b10: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e 44   to xOpen.  {END
7b20: 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  }  The xOpen met
7b30: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
7b40: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
7b50: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
7b60: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
7b70: 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a 2a  ill it in..** .*
7b80: 2a 20 7b 46 31 31 31 34 39 7d 20 54 68 65 20 66  * {F11149} The f
7b90: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7ba0: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
7bb0: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
7bc0: 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20  _EXISTS] .** to 
7bd0: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
7be0: 73 74 61 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stance of a file
7bf0: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
7c00: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
7c10: 5d 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65  ] to test to see
7c20: 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65 20 69 73  .** if a file is
7c30: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
7c40: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
7c50: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
7c60: 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65  ** to test to se
7c70: 65 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 61  e if a file is a
7c80: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
7c90: 2e 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c  .  {END} The fil
7ca0: 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64  e can be a .** d
7cb0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a  irectory..** .**
7cc0: 20 7b 46 31 31 31 35 30 7d 20 53 51 4c 69 74 65   {F11150} SQLite
7cd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
7ce0: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
7cf0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
7d00: 73 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74  s for.** the out
7d10: 70 75 74 20 62 75 66 66 65 72 73 20 66 6f 72 20  put buffers for 
7d20: 78 47 65 74 54 65 6d 70 6e 61 6d 65 20 61 6e 64  xGetTempname and
7d30: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
7d40: 7b 46 31 31 31 35 31 7d 20 54 68 65 20 65 78 61  {F11151} The exa
7d50: 63 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68  ct.** size of th
7d60: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  e output buffer 
7d70: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
7d80: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
7d90: 20 62 6f 74 68 20 0a 2a 2a 20 6d 65 74 68 6f 64   both .** method
7da0: 73 2e 20 7b 45 4e 44 7d 20 49 66 20 74 68 65 20  s. {END} If the 
7db0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 69 73  output buffer is
7dc0: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
7dd0: 68 2c 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  h, SQLITE_CANTOP
7de0: 45 4e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  EN.** should be 
7df0: 72 65 74 75 72 6e 65 64 2e 20 41 73 20 74 68 69  returned. As thi
7e00: 73 20 69 73 20 68 61 6e 64 6c 65 64 20 61 73 20  s is handled as 
7e10: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
7e20: 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 76 66 73 20   SQLite,.** vfs 
7e30: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7e40: 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 20  should endeavor 
7e50: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
7e60: 62 79 20 73 65 74 74 69 6e 67 20 0a 2a 2a 20 6d  by setting .** m
7e70: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
7e80: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
7e90: 65 20 76 61 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20  e value..** .** 
7ea0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
7eb0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64  ), xSleep(), and
7ec0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
7ed0: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
7ee0: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
7ef0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
7f00: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
7f10: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
7f20: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
7f30: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
7f40: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
7f50: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
7f60: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
7f70: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
7f80: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
7f90: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
7fa0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
7fb0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
7fc0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
7fd0: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
7fe0: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
7ff0: 20 6f 62 74 61 69 6e 65 64 2e 20 20 54 68 65 0a   obtained.  The.
8000: 2a 2a 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  ** xSleep() meth
8010: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
8020: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
8030: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
8040: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
8050: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
8060: 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75   given.  The xCu
8070: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
8080: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
8090: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
80a0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
80b0: 74 20 64 61 74 65 20 61 6e 64 0a 2a 2a 20 74 69  t date and.** ti
80c0: 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  me..*/.typedef s
80d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
80e0: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73  s sqlite3_vfs;.s
80f0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
8100: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8110: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
8120: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
8130: 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  ion number */.  
8140: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
8150: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
8160: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
8170: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
8180: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
8190: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
81a0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
81b0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
81c0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
81d0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
81e0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
81f0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
8200: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
8210: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
8220: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8230: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
8240: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
8250: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
8260: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
8270: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
8280: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
8290: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
82a0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
82b0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
82c0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
82d0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
82e0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
82f0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
8300: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8310: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
8320: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
8330: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
8340: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8350: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 29  Name, int flags)
8360: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 54 65  ;.  int (*xGetTe
8370: 6d 70 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  mpname)(sqlite3_
8380: 76 66 73 2a 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  vfs*, int nOut, 
8390: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
83a0: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
83b0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
83c0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
83d0: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
83e0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
83f0: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
8400: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
8410: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
8420: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
8430: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
8440: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
8450: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
8460: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79  .  void *(*xDlSy
8470: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
8480: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
8490: 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76  r *zSymbol);.  v
84a0: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
84b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
84c0: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
84d0: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
84e0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
84f0: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
8500: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
8510: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8520: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
8530: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
8540: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
8550: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
8560: 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    /* New fields 
8570: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
8580: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
8590: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
85a0: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
85b0: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
85c0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
85d0: 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  s. */.};../*.** 
85e0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
85f0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
8600: 56 46 53 20 6d 65 74 68 6f 64 20 7b 46 31 31 31  VFS method {F111
8610: 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 39  90}.**.** {F1119
8620: 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  1} These integer
8630: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
8640: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
8650: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
8660: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
8670: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
8680: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
8690: 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64  t. {END}  They d
86a0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
86b0: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
86c0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
86d0: 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20 6c 6f   method is.** lo
86e0: 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 7b 46 31 31  oking for.  {F11
86f0: 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45  192} With SQLITE
8700: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
8710: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
8720: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
8730: 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68  cks to see if th
8740: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 20 7b  e file exists. {
8750: 46 31 31 31 39 33 7d 20 57 69 74 68 0a 2a 2a 20  F11193} With.** 
8760: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8770: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
8780: 63 65 73 73 20 6d 65 74 68 6f 64 20 63 68 65 63  cess method chec
8790: 6b 73 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20  ks to see.** if 
87a0: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68  the file is both
87b0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
87c0: 69 74 61 62 6c 65 2e 20 20 7b 46 31 31 31 39 34  itable.  {F11194
87d0: 7d 20 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45  } With.** SQLITE
87e0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 74 68 65  _ACCESS_READ the
87f0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
8800: 2a 2a 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65  ** checks to see
8810: 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
8820: 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65  readable..*/.#de
8830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
8840: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
8850: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
8860: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
8870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8880: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
8890: 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   2../*.** CAPI3R
88a0: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
88b0: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
88c0: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 32  esult Codes {F12
88d0: 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  200}.**.** The s
88e0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
88f0: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
8900: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
8910: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
8920: 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  * [SQLITE_IOERR_
8930: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
8940: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
8950: 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
8960: 0a 2a 2a 20 54 68 65 20 65 78 74 65 6e 64 65 64  .** The extended
8970: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
8980: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
8990: 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
89a0: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
89b0: 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ility..**.** INV
89c0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
89d0: 46 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77  F12201} Each new
89e0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
89f0: 63 74 69 6f 6e 5d 20 68 61 73 20 74 68 65 20 0a  ction] has the .
8a00: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
8a10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
8a20: 65 73 5d 20 66 65 61 74 75 72 65 0a 2a 2a 20 20  es] feature.**  
8a30: 20 20 20 20 20 20 20 20 64 69 73 61 62 6c 65 64          disabled
8a40: 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
8a50: 2a 2a 20 7b 46 31 32 32 30 32 7d 20 54 68 65 20  ** {F12202} The 
8a60: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
8a70: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44  d_result_codes(D
8a80: 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  ,F)] interface w
8a90: 69 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20  ill enable.**   
8aa0: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
8ab0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
8ac0: 6f 72 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  or the .**      
8ad0: 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
8ae0: 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 66 20 74  nnection] D if t
8af0: 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 0a 2a  he F parameter.*
8b00: 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 74 72  *          is tr
8b10: 75 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ue, or disable t
8b20: 68 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73  hem if F is fals
8b30: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
8b40: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
8b50: 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
8b60: 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
8b70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
8b80: 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
8b90: 20 7b 46 31 32 32 32 30 7d 0a 2a 2a 0a 2a 2a 20   {F12220}.**.** 
8ba0: 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
8bb0: 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
8bc0: 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
8bd0: 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
8be0: 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
8bf0: 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20  he "rowid". The 
8c00: 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
8c10: 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
8c20: 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
8c30: 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
8c40: 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
8c50: 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
8c60: 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
8c70: 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
8c80: 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
8c90: 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66  ared columns. If
8ca0: 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
8cb0: 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
8cc0: 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  pe INTEGER PRIMA
8cd0: 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74  RY KEY then that
8ce0: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
8cf0: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
8d00: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
8d10: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
8d20: 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20  turns the rowid 
8d30: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
8d40: 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  nt.** successful
8d50: 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 65   INSERT into the
8d60: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
8d70: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
8d80: 65 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 77 6e 20  ection.** shown 
8d90: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
8da0: 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75  ument.  If no su
8db0: 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 73  ccessful inserts
8dc0: 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
8dd0: 63 75 72 72 65 64 20 6f 6e 20 74 68 69 73 20 64  curred on this d
8de0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8df0: 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
8e00: 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  rned..**.** If a
8e10: 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20  n INSERT occurs 
8e20: 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
8e30: 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64  , then the rowid
8e40: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65 72   of the.** inser
8e50: 74 65 64 20 72 6f 77 20 69 73 20 72 65 74 75 72  ted row is retur
8e60: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
8e70: 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
8e80: 68 65 20 74 72 69 67 67 65 72 0a 2a 2a 20 69 73  he trigger.** is
8e90: 20 72 75 6e 6e 69 6e 67 2e 20 20 42 75 74 20 6f   running.  But o
8ea0: 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
8eb0: 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20  terminates, the 
8ec0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
8ed0: 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
8ee0: 65 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65  e reverts to the
8ef0: 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65   last value inse
8f00: 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 0a  rted before the.
8f10: 2a 2a 20 74 72 69 67 67 65 72 20 66 69 72 65 64  ** trigger fired
8f20: 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52  ..**.** An INSER
8f30: 54 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  T that fails due
8f40: 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
8f50: 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
8f60: 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
8f70: 6c 20 69 6e 73 65 72 74 20 61 6e 64 20 64 6f 65  l insert and doe
8f80: 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
8f90: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
8fa0: 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
8fb0: 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54  ne.  Thus INSERT
8fc0: 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
8fd0: 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
8fe0: 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
8ff0: 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
9000: 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
9010: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
9020: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
9030: 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
9040: 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
9050: 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20  on fails.  When 
9060: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
9070: 45 20 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  E .** encounters
9080: 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
9090: 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
90a0: 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
90b0: 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
90c0: 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
90d0: 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
90e0: 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
90f0: 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
9100: 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
9110: 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
9120: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
9130: 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
9140: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
9150: 69 6e 74 65 72 66 61 63 65 2e 20 0a 2a 2a 0a 2a  interface. .**.*
9160: 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
9170: 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
9180: 6e 65 2c 20 61 6e 20 69 6e 73 65 72 74 20 69 73  ne, an insert is
9190: 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
91a0: 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
91b0: 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
91c0: 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
91d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e  d back..**.** IN
91e0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
91f0: 7b 46 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71  {F12221} The [sq
9200: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
9210: 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74  t_rowid()] funct
9220: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
9230: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 69  **          rowi
9240: 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  d of the most re
9250: 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
9260: 69 6e 73 65 72 74 20 64 6f 6e 65 0a 2a 2a 20 20  insert done.**  
9270: 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73          on the s
9280: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
9290: 6e 65 63 74 69 6f 6e 20 61 6e 64 20 77 69 74 68  nection and with
92a0: 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  in the same.**  
92b0: 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20          trigger 
92c0: 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f  context, or zero
92d0: 20 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a   if there have.*
92e0: 2a 20 20 20 20 20 20 20 20 20 20 62 65 65 6e 20  *          been 
92f0: 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69 6e  no qualifying in
9300: 73 65 72 74 73 20 6f 6e 20 74 68 61 74 20 63 6f  serts on that co
9310: 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nnection..**.** 
9320: 7b 46 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71  {F12223} The [sq
9330: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
9340: 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74  t_rowid()] funct
9350: 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ion returns.**  
9360: 20 20 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c          same val
9370: 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  ue when called f
9380: 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69  rom the same tri
9390: 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20  gger context.** 
93a0: 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61           immedia
93b0: 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20  tely before and 
93c0: 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b  after a ROLLBACK
93d0: 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49  ..**.** LIMITATI
93e0: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32  ONS:.**.** {U122
93f0: 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  32} If a separat
9400: 65 20 74 68 72 65 61 64 20 64 6f 65 73 20 61 20  e thread does a 
9410: 6e 65 77 20 69 6e 73 65 72 74 20 6f 6e 20 74 68  new insert on th
9420: 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
9430: 20 20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e     database conn
9440: 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
9450: 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
9460: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
9470: 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
9480: 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
9490: 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
94a0: 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
94b0: 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20  rowid,.**       
94c0: 20 20 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75     then the valu
94d0: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
94e0: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
94f0: 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
9500: 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70 72 65  *          unpre
9510: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
9520: 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
9530: 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
9540: 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20  he new.**       
9550: 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72     last insert r
9560: 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  owid..*/.sqlite3
9570: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
9580: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
9590: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
95a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
95b0: 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
95c0: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
95d0: 46 31 32 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12240}.**.** Th
95e0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
95f0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
9600: 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
9610: 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
9620: 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
9630: 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
9640: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
9650: 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
9660: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
9670: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  he connection sp
9680: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
9690: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
96a0: 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 73   Only.** changes
96b0: 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
96c0: 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
96d0: 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41  the INSERT, UPDA
96e0: 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 45  TE, or.** DELETE
96f0: 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
9700: 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
9710: 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
9720: 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
9730: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
9740: 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74  . Use the [sqlit
9750: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
9760: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ()] function.** 
9770: 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
9780: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
9790: 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  ges including ch
97a0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
97b0: 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  triggers..**.** 
97c0: 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
97d0: 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
97e0: 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
97f0: 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
9800: 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
9810: 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
9820: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
9830: 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
9840: 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
9850: 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52  ide effects of R
9860: 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
9870: 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
9880: 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
9890: 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f   processing, DRO
98a0: 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61  P TABLE, or by a
98b0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
98c0: 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
98d0: 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
98e0: 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a  w changes..**.**
98f0: 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
9900: 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
9910: 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
9920: 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
9930: 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
9940: 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65  ript of a trigge
9950: 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  r.  Most SQL sta
9960: 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
9970: 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
9980: 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
9990: 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
99a0: 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
99b0: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
99c0: 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
99d0: 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
99e0: 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
99f0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
9a00: 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
9a10: 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
9a20: 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
9a30: 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
9a40: 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
9a50: 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
9a60: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  ation..**.** Cal
9a70: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
9a80: 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
9a90: 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
9aa0: 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
9ab0: 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
9ac0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
9ad0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
9ae0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
9af0: 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
9b00: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
9b10: 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
9b20: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
9b30: 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
9b40: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
9b50: 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
9b60: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
9b70: 20 53 6f 20 77 68 65 6e 20 63 61 6c 6c 65 64 20   So when called 
9b80: 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
9b90: 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
9ba0: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
9bb0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
9bc0: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
9bd0: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
9be0: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
9bf0: 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
9c00: 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
9c10: 20 6c 65 76 65 6c 2e 0a 2a 2a 20 57 69 74 68 69   level..** Withi
9c20: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
9c30: 74 72 69 67 67 65 72 2c 20 74 68 65 20 73 71 6c  trigger, the sql
9c40: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
9c50: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 6e 20  nterface.** can 
9c60: 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
9c70: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
9c80: 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
9c90: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
9ca0: 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
9cb0: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
9cc0: 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
9cd0: 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
9ce0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
9cf0: 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
9d00: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
9d10: 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
9d20: 6e 63 6c 75 64 65 20 69 6e 20 63 68 61 6e 67 65  nclude in change
9d30: 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
9d40: 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
9d50: 20 74 68 65 79 20 68 61 76 65 20 74 68 65 69 72   they have their
9d60: 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a   own context..**
9d70: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
9d80: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
9d90: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
9da0: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a  able" without.**
9db0: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 20   a WHERE clause 
9dc0: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
9dd0: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
9de0: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
9df0: 6d 75 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 74  much.** faster t
9e00: 68 61 6e 20 67 6f 69 6e 67 20 74 68 72 6f 75 67  han going throug
9e10: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
9e20: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
9e30: 74 73 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  ts from the.** t
9e40: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
9e50: 6f 66 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61  of this optimiza
9e60: 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69  tion, the deleti
9e70: 6f 6e 73 20 69 6e 0a 2a 2a 20 22 44 45 4c 45 54  ons in.** "DELET
9e80: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
9e90: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
9ea0: 73 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62  s and will not b
9eb0: 65 20 63 6f 75 6e 74 65 64 0a 2a 2a 20 62 79 20  e counted.** by 
9ec0: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
9ed0: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
9ee0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
9ef0: 29 5d 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  )] functions..**
9f00: 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72   To get an accur
9f10: 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  ate count of the
9f20: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
9f30: 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20  deleted, use.** 
9f40: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
9f50: 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74  le WHERE 1" inst
9f60: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ead..**.** INVAR
9f70: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
9f80: 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2241} The [sqlit
9f90: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  e3_changes()] fu
9fa0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
9fb0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
9fc0: 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 68 61           row cha
9fd0: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
9fe0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
9ff0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a  NSERT, UPDATE,.*
a000: 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 44 45  *          or DE
a010: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f  LETE statement o
a020: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
a030: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  ase connection a
a040: 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nd.**          w
a050: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
a060: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20  rigger context, 
a070: 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65  or zero if there
a080: 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
a090: 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71    not been any q
a0a0: 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68  ualifying row ch
a0b0: 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  anges..**.** LIM
a0c0: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
a0d0: 7b 55 31 32 32 35 32 7d 20 49 66 20 61 20 73 65  {U12252} If a se
a0e0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
a0f0: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
a100: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
a110: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
a120: 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73          while [s
a130: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
a140: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
a150: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
a160: 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
a170: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
a180: 65 20 61 6e 64 20 75 6e 6d 65 61 6e 69 6e 67 66  e and unmeaningf
a190: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
a1a0: 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
a1b0: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
a1c0: 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
a1d0: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
a1e0: 66 69 65 64 20 7b 46 31 32 32 36 30 7d 0a 2a 2a  fied {F12260}.**
a1f0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
a200: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
a210: 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
a220: 6e 67 65 73 20 63 61 75 73 65 64 0a 2a 2a 20 62  nges caused.** b
a230: 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  y INSERT, UPDATE
a240: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
a250: 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
a260: 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 0a  database handle.
a270: 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e 20 20  ** was opened.  
a280: 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64  The count includ
a290: 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66  es all changes f
a2a0: 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 0a  rom all trigger.
a2b0: 2a 2a 20 63 6f 6e 74 65 78 74 73 2e 20 20 42 75  ** contexts.  Bu
a2c0: 74 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  t the count does
a2d0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
a2e0: 6e 67 65 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20  nges used to.** 
a2f0: 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43  implement REPLAC
a300: 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 20 64  E constraints, d
a310: 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
a320: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
a330: 0a 2a 2a 20 6f 72 20 44 52 4f 50 20 74 61 62 6c  .** or DROP tabl
a340: 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a  e processing..**
a350: 20 54 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20   The changes.** 
a360: 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73  are counted as s
a370: 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65  oon as the state
a380: 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
a390: 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
a3a0: 64 20 0a 2a 2a 20 28 77 68 65 6e 20 74 68 65 20  d .** (when the 
a3b0: 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
a3c0: 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
a3d0: 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
a3e0: 6f 72 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  or .** [sqlite3_
a3f0: 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
a400: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
a410: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
a420: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
a430: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a  able" without.**
a440: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 20   a WHERE clause 
a450: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
a460: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
a470: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
a480: 6d 75 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 74  much.** faster t
a490: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72  han going.** thr
a4a0: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
a4b0: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
a4c0: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74  ments from the t
a4d0: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
a4e0: 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d  of.** this optim
a4f0: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61  ization, the cha
a500: 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44  nge count for "D
a510: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
a520: 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72  " will be.** zer
a530: 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  o regardless of 
a540: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c  the number of el
a550: 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65  ements that were
a560: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74   originally in t
a570: 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20  he.** table. To 
a580: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
a590: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
a5a0: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
a5b0: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
a5c0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
a5d0: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
a5e0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
a5f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
a600: 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
a610: 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
a620: 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32  NTS:.** .** {F12
a630: 32 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  261} The [sqlite
a640: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
a650: 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  )] returns the t
a660: 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20  otal number.**  
a670: 20 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63          of row c
a680: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
a690: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
a6a0: 20 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a   and/or DELETE.*
a6b0: 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65  *          state
a6c0: 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d  ments on the sam
a6d0: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
a6e0: 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a  ection], in any.
a6f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67  **          trig
a700: 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e  ger context, sin
a710: 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
a720: 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 0a 2a  connection was.*
a730: 2a 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74  *          creat
a740: 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  ed..**.** LIMITA
a750: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
a760: 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72  2264} If a separ
a770: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
a780: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
a790: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
a7a0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
a7b0: 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69       while [sqli
a7c0: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
a7d0: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
a7e0: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 0a  then the value .
a7f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
a800: 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
a810: 74 61 62 6c 65 20 61 6e 64 20 75 6e 6d 65 61 6e  table and unmean
a820: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
a830: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
a840: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
a850: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a860: 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
a870: 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20  g-Running Query 
a880: 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12270}.**.** T
a890: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
a8a0: 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
a8b0: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
a8c0: 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
a8d0: 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
a8e0: 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
a8f0: 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
a900: 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
a910: 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
a920: 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
a930: 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
a940: 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
a950: 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
a960: 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
a970: 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
a980: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
a990: 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
a9a0: 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73  y..**.** It is s
a9b0: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
a9c0: 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
a9d0: 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
a9e0: 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
a9f0: 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
aa00: 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
aa10: 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
aa20: 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
aa30: 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
aa40: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
aa50: 65 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  e with a databas
aa60: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
aa70: 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
aa80: 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
aa90: 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
aaa0: 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
aab0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51  ..**.** If an SQ
aac0: 4c 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  L is very nearly
aad0: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
aae0: 20 74 69 6d 65 20 77 68 65 6e 20 73 71 6c 69 74   time when sqlit
aaf0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 0a 2a  e3_interrupt().*
ab00: 2a 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  * is called, the
ab10: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
ab20: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
ab30: 74 79 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ty to be interru
ab40: 70 74 65 64 2e 0a 2a 2a 20 49 74 20 6d 69 67 68  pted..** It migh
ab50: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
ab60: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 20 41 6e 20  mpletion..** An 
ab70: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
ab80: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
ab90: 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  d will return.**
aba0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
abb0: 50 54 5d 2e 20 20 49 66 20 74 68 65 20 69 6e 74  PT].  If the int
abc0: 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
abd0: 72 61 74 69 6f 6e 20 69 73 20 61 6e 0a 2a 2a 20  ration is an.** 
abe0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
abf0: 6f 72 20 44 45 4c 45 54 45 20 74 68 61 74 20 69  or DELETE that i
ac00: 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
ac10: 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
ac20: 2c 20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 65  , .** then the e
ac30: 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
ac40: 6e 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  n will be rolled
ac50: 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
ac60: 6c 6c 79 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  lly..** A call t
ac70: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
ac80: 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66  upt() has no eff
ac90: 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
aca0: 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
acb0: 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
acc0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
acd0: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
ace0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
acf0: 2a 0a 2a 2a 20 7b 46 31 32 32 37 31 7d 20 54 68  *.** {F12271} Th
ad00: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
ad10: 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61 63  rupt()] interfac
ad20: 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c  e will force all
ad30: 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20   running.**     
ad40: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
ad50: 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
ad60: 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61 74  ith the same dat
ad70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ad80: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
ad90: 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63 65  halt after proce
ada0: 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e  ssing at most on
adb0: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77  e additional row
adc0: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
add0: 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  data..**.** {F12
ade0: 32 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61  272} Any SQL sta
adf0: 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69  tement that is i
ae00: 6e 74 65 72 72 75 70 74 65 64 20 62 79 20 5b 73  nterrupted by [s
ae10: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
ae20: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
ae30: 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
ae40: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
ae50: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
ae60: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 37 39  S:.**.** {U12279
ae70: 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  } If the databas
ae80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
ae90: 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
aea0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
aeb0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 72  **          is r
aec0: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
aed0: 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
aee0: 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
aef0: 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
af00: 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
af10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
af20: 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
af30: 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
af40: 73 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30 35  s Complete {F105
af50: 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  10}.**.** These 
af60: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
af70: 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d  ful for command-
af80: 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
af90: 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
afa0: 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
afb0: 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
afc0: 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20  o form complete 
afd0: 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  a SQL statement 
afe0: 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
aff0: 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
b000: 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
b010: 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
b020: 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
b030: 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72  arsing.  These r
b040: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
b050: 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 74  rue if the input
b060: 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
b070: 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
b080: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
b090: 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20  t.  A statement 
b0a0: 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
b0b0: 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
b0c0: 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
b0d0: 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
b0e0: 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d  d is not a fragm
b0f0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41  ent of a.** CREA
b100: 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
b110: 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e  ment.  Semicolon
b120: 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
b130: 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
b140: 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
b150: 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
b160: 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
b170: 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
b180: 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
b190: 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
b1a0: 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
b1b0: 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
b1c0: 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
b1d0: 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
b1e0: 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
b1f0: 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  nt terminator..*
b200: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
b210: 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
b220: 20 74 68 65 20 53 51 4c 20 61 6e 64 0a 2a 2a 20   the SQL and.** 
b230: 73 6f 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  so will not dete
b240: 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
b250: 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
b260: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
b270: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31 7d  :.**.** {F10511}
b280: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d   The sqlite3_com
b290: 70 6c 65 74 65 28 29 20 61 6e 64 20 73 71 6c 69  plete() and sqli
b2a0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
b2b0: 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 20 20   functions.**   
b2c0: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 74 72         return tr
b2d0: 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
b2e0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
b2f0: 20 6c 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20   last.**        
b300: 20 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63 65    non-whitespace
b310: 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20   token in their 
b320: 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 63  input is a semic
b330: 6f 6c 6f 6e 20 74 68 61 74 0a 2a 2a 20 20 20 20  olon that.**    
b340: 20 20 20 20 20 20 69 73 20 6e 6f 74 20 69 6e 20        is not in 
b350: 62 65 74 77 65 65 6e 20 74 68 65 20 42 45 47 49  between the BEGI
b360: 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43  N and END of a C
b370: 52 45 41 54 45 20 54 52 49 47 47 45 52 0a 2a 2a  REATE TRIGGER.**
b380: 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
b390: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  ent..**.** LIMIT
b3a0: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
b3b0: 31 30 35 31 32 7d 20 54 68 65 20 69 6e 70 75 74  10512} The input
b3c0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
b3d0: 6c 65 74 65 28 29 20 6d 75 73 74 20 62 65 20 61  lete() must be a
b3e0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
b3f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46  .**          UTF
b400: 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
b410: 20 7b 55 31 30 35 31 33 7d 20 54 68 65 20 69 6e   {U10513} The in
b420: 70 75 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  put to sqlite3_c
b430: 6f 6d 70 6c 65 74 65 31 36 28 29 20 6d 75 73 74  omplete16() must
b440: 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
b450: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
b460: 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20    UTF-16 string 
b470: 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
b480: 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
b490: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
b4a0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
b4b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
b4c0: 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
b4d0: 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
b4e0: 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
b4f0: 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
b500: 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
b510: 55 53 59 20 45 72 72 6f 72 73 20 7b 46 31 32 33  USY Errors {F123
b520: 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10}.**.** This r
b530: 6f 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65  outine identifie
b540: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
b550: 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
b560: 20 62 65 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77   be.** invoked w
b570: 68 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d  henever an attem
b580: 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
b590: 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
b5a0: 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f  ble .** that ano
b5b0: 74 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70  ther thread or p
b5c0: 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
b5d0: 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73  d..** If the bus
b5e0: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
b5f0: 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
b600: 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
b610: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
b620: 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
b630: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
b640: 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
b650: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66   the lock..** If
b660: 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
b670: 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ck is not NULL, 
b680: 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  then the.** call
b690: 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76  back will be inv
b6a0: 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
b6b0: 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a  guments.  The.**
b6c0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
b6d0: 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69  to the handler i
b6e0: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
b6f0: 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
b700: 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
b710: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
b720: 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 54  this routine.  T
b730: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
b740: 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e  nt to.** the han
b750: 64 6c 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62  dler is the numb
b760: 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
b770: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
b780: 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
b790: 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
b7a0: 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 20  ocking event.   
b7b0: 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
b7c0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
b7d0: 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
b7e0: 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
b7f0: 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
b800: 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
b810: 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
b820: 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
b830: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
b840: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
b850: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
b860: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
b870: 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
b880: 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
b890: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
b8a0: 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
b8b0: 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
b8c0: 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
b8d0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
b8e0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
b8f0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
b900: 74 68 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20  that.** it will 
b910: 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  be invoked when 
b920: 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
b930: 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20  ntention..** If 
b940: 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
b950: 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
b960: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
b970: 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
b980: 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20  .** a deadlock, 
b990: 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
b9a0: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
b9b0: 49 54 45 5f 42 55 53 59 5d 20 6f 72 0a 2a 2a 20  ITE_BUSY] or.** 
b9c0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
b9d0: 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
b9e0: 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 0a 2a  f invoking the.*
b9f0: 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
ba00: 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
ba10: 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
ba20: 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
ba30: 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
ba40: 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
ba50: 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
ba60: 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
ba70: 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
ba80: 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
ba90: 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
baa0: 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
bab0: 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
bac0: 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
bad0: 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
bae0: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
baf0: 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
bb00: 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
bb10: 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
bb20: 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
bb30: 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
bb40: 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
bb50: 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
bb60: 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
bb70: 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
bb80: 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
bb90: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
bba0: 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
bbb0: 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
bbc0: 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
bbd0: 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
bbe0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
bbf0: 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
bc00: 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
bc10: 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
bc20: 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
bc30: 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
bc40: 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
bc50: 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
bc60: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
bc70: 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
bc80: 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75  * The default bu
bc90: 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
bca0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
bcb0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
bcc0: 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
bcd0: 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
bce0: 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
bcf0: 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
bd00: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
bd10: 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
bd20: 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
bd30: 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
bd40: 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
bd50: 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
bd60: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
bd70: 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
bd80: 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
bd90: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
bda0: 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
bdb0: 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
bdc0: 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
bdd0: 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
bde0: 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
bdf0: 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
be00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
be10: 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
be20: 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
be30: 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69  eaders.  If it i
be40: 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
be50: 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
be60: 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
be70: 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
be80: 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
be90: 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
bea0: 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
beb0: 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
bec0: 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
bed0: 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
bee0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
bef0: 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
bf00: 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
bf10: 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69  R_BLOCKED].  Thi
bf20: 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
bf30: 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
bf40: 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
bf50: 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
bf60: 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
bf70: 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70  ** <a href="http
bf80: 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72  ://www.sqlite.or
bf90: 67 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  g/cvstrac/wiki?p
bfa0: 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
bfb0: 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
bfc0: 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
bfd0: 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
bfe0: 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
bff0: 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
c000: 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
c010: 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a   important..**..
c020: 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c  ** There can onl
c030: 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
c040: 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
c050: 65 64 20 66 6f 72 20 65 61 63 68 20 64 61 74 61  ed for each data
c060: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
c070: 6f 6e 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  on.  Setting a n
c080: 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
c090: 63 6c 65 61 72 73 20 61 6e 79 20 70 72 65 76 69  clears any previ
c0a0: 6f 75 73 20 6f 6e 65 2e 20 0a 2a 2a 20 4e 6f 74  ous one. .** Not
c0b0: 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
c0c0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
c0d0: 65 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73  eout()] will als
c0e0: 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a  o set or clear.*
c0f0: 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
c100: 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  er..**.** INVARI
c110: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
c120: 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  311} The [sqlite
c130: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
c140: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  ] function repla
c150: 63 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e  ces the busy han
c160: 64 6c 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  dler.**         
c170: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65   callback in the
c180: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
c190: 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20  tion identified 
c1a0: 62 79 20 74 68 65 20 31 73 74 0a 2a 2a 20 20 20  by the 1st.**   
c1b0: 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
c1c0: 20 77 69 74 68 20 61 20 6e 65 77 20 62 75 73 79   with a new busy
c1d0: 20 68 61 6e 64 6c 65 72 20 69 64 65 6e 74 69 66   handler identif
c1e0: 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 61  ied by the 2nd a
c1f0: 6e 64 20 33 72 64 0a 2a 2a 20 20 20 20 20 20 20  nd 3rd.**       
c200: 20 20 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a     parameters..*
c210: 2a 0a 2a 2a 20 7b 46 31 32 33 31 32 7d 20 54 68  *.** {F12312} Th
c220: 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 68  e default busy h
c230: 61 6e 64 6c 65 72 20 66 6f 72 20 6e 65 77 20 64  andler for new d
c240: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c250: 6f 6e 73 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ons is NULL..**.
c260: 2a 2a 20 7b 46 31 32 33 31 34 7d 20 57 68 65 6e  ** {F12314} When
c270: 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 64 61 74   two or more dat
c280: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c290: 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20   share a common 
c2a0: 63 61 63 68 65 2c 0a 2a 2a 20 20 20 20 20 20 20  cache,.**       
c2b0: 20 20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64     the busy hand
c2c0: 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  ler for the data
c2d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c2e0: 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a  currently using.
c2f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
c300: 63 61 63 68 65 20 69 73 20 69 6e 76 6f 6b 65 64  cache is invoked
c310: 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20   when the cache 
c320: 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63  encounters a loc
c330: 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 36  k..**.** {F12316
c340: 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64  } If a busy hand
c350: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ler callback ret
c360: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  urns zero, then 
c370: 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20  the SQLite.**   
c380: 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
c390: 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74   that provoked t
c3a0: 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  he locking event
c3b0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
c3c0: 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
c3d0: 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _BUSY]..**.** {F
c3e0: 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20 77 69  12318} SQLite wi
c3f0: 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62  ll invokes the b
c400: 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68  usy handler with
c410: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 20 77 68   two argument wh
c420: 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ich.**          
c430: 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  are a copy of th
c440: 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69  e pointer suppli
c450: 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61  ed by the 3rd pa
c460: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
c470: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
c480: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20  busy_handler()] 
c490: 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74  and a count of t
c4a0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69  he number of pri
c4b0: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  or.**          i
c4c0: 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
c4d0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
c4e0: 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
c4f0: 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a  ing event..**.**
c500: 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
c510: 0a 2a 2a 20 7b 55 31 32 33 31 39 7d 20 41 20 62  .** {U12319} A b
c520: 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 6f 75  usy handler shou
c530: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 63 6c 6f 73  ld not call clos
c540: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
c550: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
c560: 20 20 20 20 20 20 6f 72 20 70 72 65 70 61 72 65        or prepare
c570: 64 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  d statement that
c580: 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
c590: 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
c5a0: 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
c5b0: 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
c5c0: 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
c5d0: 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
c5e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
c5f0: 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20   A Busy Timeout 
c600: 7b 46 31 32 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12340}.**.** T
c610: 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
c620: 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
c630: 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
c640: 68 61 6e 64 6c 65 72 5d 0a 2a 2a 20 74 68 61 74  handler].** that
c650: 20 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77 68   sleeps for a wh
c660: 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61  ile when a.** ta
c670: 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
c680: 54 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c  The handler will
c690: 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
c6a0: 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20  times until .** 
c6b0: 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
c6c0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
c6d0: 65 65 70 69 6e 67 20 68 61 76 65 20 62 65 65 6e  eeping have been
c6e0: 20 64 6f 6e 65 2e 20 7b 46 31 32 33 34 33 7d 20   done. {F12343} 
c6f0: 41 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69  After.** "ms" mi
c700: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
c710: 65 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e 64  eeping, the hand
c720: 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
c730: 69 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73  ich.** causes [s
c740: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
c750: 6f 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  o return [SQLITE
c760: 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
c770: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
c780: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
c790: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
c7a0: 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
c7b0: 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
c7c0: 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
c7d0: 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
c7e0: 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  andlers..**.** T
c7f0: 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
c800: 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
c810: 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
c820: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
c830: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
c840: 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
c850: 20 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65 66   handler was def
c860: 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e 67  ined  .** (using
c870: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
c880: 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
c890: 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
c8a0: 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
c8b0: 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
c8c0: 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
c8d0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
c8e0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 31  S:.**.** {F12341
c8f0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
c900: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66  usy_timeout()] f
c910: 75 6e 63 74 69 6f 6e 20 6f 76 65 72 72 69 64 65  unction override
c920: 73 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20  s any prior.**  
c930: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
c940: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
c950: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   or [sqlite3_bus
c960: 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74  y_handler()] set
c970: 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ting.**         
c980: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
c990: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c9a0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 33 7d  ..**.** {F12343}
c9b0: 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
c9c0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
c9d0: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
c9e0: 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a  ] is less than.*
c9f0: 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 65 71  *          or eq
ca00: 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65  ual to zero, the
ca10: 6e 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  n the busy handl
ca20: 65 72 20 69 73 20 63 6c 65 61 72 65 64 20 73 6f  er is cleared so
ca30: 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
ca40: 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74    all subsequent
ca50: 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20   locking events 
ca60: 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75  immediately retu
ca70: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
ca80: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 34 7d  ..**.** {F12344}
ca90: 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
caa0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
cab0: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
cac0: 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a  ] is a positive.
cad0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
cae0: 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73  er N, then a bus
caf0: 79 20 68 61 6e 64 6c 65 72 20 69 73 20 73 65 74  y handler is set
cb00: 20 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79   that repeatedly
cb10: 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20   calls.**       
cb20: 20 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20     the xSleep() 
cb30: 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 56 46  method in the VF
cb40: 53 20 69 6e 74 65 72 66 61 63 65 20 75 6e 74 69  S interface unti
cb50: 6c 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  l either the.** 
cb60: 20 20 20 20 20 20 20 20 20 6c 6f 63 6b 20 63 6c           lock cl
cb70: 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68  ears or until th
cb80: 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65  e cumulative sle
cb90: 65 70 20 74 69 6d 65 20 72 65 70 6f 72 74 65 64  ep time reported
cba0: 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20   back.**        
cbb0: 20 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78    by xSleep() ex
cbc0: 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63  ceeds N millisec
cbd0: 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  onds..*/.int sql
cbe0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
cbf0: 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
cc00: 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
cc10: 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
cc20: 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
cc30: 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b  unning Queries {
cc40: 46 31 32 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 65  F12370}.**.** De
cc50: 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
cc60: 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
cc70: 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
cc80: 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
cc90: 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
cca0: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
ccb0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
ccc0: 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
ccd0: 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
cce0: 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
ccf0: 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
cd00: 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
cd10: 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
cd20: 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
cd30: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
cd40: 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
cd50: 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
cd60: 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
cd70: 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
cd80: 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
cd90: 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
cda0: 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
cdb0: 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
cdc0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
cdd0: 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
cde0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
cdf0: 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
ce00: 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
ce10: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
ce20: 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
ce30: 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
ce40: 72 69 6e 67 73 2e 20 20 54 68 65 72 65 20 61 72  rings.  There ar
ce50: 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
ce60: 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
ce70: 20 20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20    .** The first 
ce80: 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
ce90: 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
cea0: 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
ceb0: 20 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 74 68 65   .** contain the
cec0: 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
ced0: 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
cee0: 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
cef0: 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
cf00: 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
cf10: 4c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 72 65 20  L.** values are 
cf20: 67 69 76 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  give a NULL poin
cf30: 74 65 72 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ter.  All other 
cf40: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 0a 2a 2a  values are in.**
cf50: 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
cf60: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
cf70: 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
cf80: 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
cf90: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
cfa0: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
cfb0: 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
cfc0: 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
cfd0: 73 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  s of one or more
cfe0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cff0: 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
d000: 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
d010: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
d020: 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
d030: 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
d040: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
d050: 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
d060: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
d070: 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
d080: 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78  ..**.** As an ex
d090: 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
d0a0: 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
d0b0: 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
d0c0: 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
d0d0: 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
d0e0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
d0f0: 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
d100: 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
d110: 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
d120: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
d130: 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
d140: 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
d150: 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
d160: 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
d170: 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
d180: 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
d190: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
d1a0: 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
d1b0: 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
d1c0: 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
d1d0: 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
d1e0: 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
d1f0: 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
d200: 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
d210: 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
d220: 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
d230: 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
d240: 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
d250: 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
d260: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
d270: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
d280: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
d290: 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
d2a0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
d2b0: 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
d2c0: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
d2d0: 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
d2e0: 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
d2f0: 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
d300: 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
d310: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
d320: 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
d330: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
d340: 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
d350: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
d360: 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
d370: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
d380: 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
d390: 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
d3a0: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
d3b0: 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
d3c0: 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
d3d0: 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
d3e0: 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
d3f0: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
d400: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
d410: 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
d420: 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
d430: 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
d440: 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65  arameter.  It re
d450: 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
d460: 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
d470: 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
d480: 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
d490: 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
d4a0: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
d4b0: 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
d4c0: 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c   using the resul
d4d0: 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  t, it should .**
d4e0: 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
d4f0: 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20  r to the result 
d500: 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33  table to sqlite3
d510: 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
d520: 20 6f 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72 65   order to .** re
d530: 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
d540: 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
d550: 2d 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  -ed.  Because of
d560: 20 74 68 65 20 77 61 79 20 74 68 65 20 0a 2a 2a   the way the .**
d570: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
d580: 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
d590: 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
d5a0: 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
d5b0: 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
d5c0: 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
d5d0: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
d5e0: 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
d5f0: 20 4f 6e 6c 79 20 0a 2a 2a 20 5b 73 71 6c 69 74   Only .** [sqlit
d600: 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
d610: 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
d620: 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
d630: 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
d640: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
d650: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
d660: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
d670: 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
d680: 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
d690: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
d6a0: 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
d6b0: 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
d6c0: 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
d6d0: 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
d6e0: 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
d6f0: 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
d700: 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
d710: 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
d720: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
d730: 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
d740: 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
d750: 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
d760: 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
d770: 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
d780: 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
d790: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
d7a0: 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
d7b0: 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
d7c0: 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
d7d0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
d7e0: 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
d7f0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
d800: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
d810: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 31  S:.**.** {F12371
d820: 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  } If a [sqlite3_
d830: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69  get_table()] fai
d840: 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ls a memory allo
d850: 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  cation, then.** 
d860: 20 20 20 20 20 20 20 20 20 69 74 20 66 72 65 65           it free
d870: 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
d880: 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75  le under constru
d890: 63 74 69 6f 6e 2c 20 61 62 6f 72 74 73 20 74 68  ction, aborts th
d8a0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75  e.**          qu
d8b0: 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20  ery in process, 
d8c0: 73 6b 69 70 73 20 61 6e 79 20 73 75 62 73 65 71  skips any subseq
d8d0: 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65  uent queries, se
d8e0: 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
d8f0: 20 20 20 2a 72 65 73 75 6c 74 70 20 6f 75 74 70     *resultp outp
d900: 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55  ut pointer to NU
d910: 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 5b  LL and returns [
d920: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
d930: 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20 49 66  *.** {F12373} If
d940: 20 74 68 65 20 6e 63 6f 6c 75 6d 6e 20 70 61 72   the ncolumn par
d950: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
d960: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
d970: 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20  is not NULL.**  
d980: 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
d990: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
d9a0: 29 5d 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d  )] write the num
d9b0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
d9c0: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
d9d0: 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
d9e0: 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
d9f0: 6e 63 6f 6c 75 6d 6e 20 69 66 20 74 68 65 20 71  ncolumn if the q
da00: 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20 20  uery is.**      
da10: 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20 28      successful (
da20: 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  if the function 
da30: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
da40: 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37  K)..**.** {F1237
da50: 34 7d 20 49 66 20 74 68 65 20 6e 72 6f 77 20 70  4} If the nrow p
da60: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
da70: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
da80: 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
da90: 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
daa0: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
dab0: 65 28 29 5d 20 77 72 69 74 65 20 74 68 65 20 6e  e()] write the n
dac0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
dad0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
dae0: 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
daf0: 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 6e  he query into *n
db00: 72 6f 77 20 69 66 20 74 68 65 20 71 75 65 72 79  row if the query
db10: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
db20: 73 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 74  successful (if t
db30: 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
db40: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a  rns SQLITE_OK)..
db50: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 36 7d 20 54  **.** {F12376} T
db60: 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
db70: 74 61 62 6c 65 28 29 5d 20 66 75 6e 63 74 69 6f  table()] functio
db80: 6e 20 73 65 74 73 20 69 74 73 20 2a 6e 63 6f 6c  n sets its *ncol
db90: 75 6d 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  umn value.**    
dba0: 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 75 6d        to the num
dbb0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
dbc0: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
dbd0: 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
dbe0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
dbf0: 20 73 71 6c 20 70 61 72 61 6d 65 74 65 72 2c 20   sql parameter, 
dc00: 6f 72 20 74 6f 20 7a 65 72 6f 20 69 66 20 74 68  or to zero if th
dc10: 65 20 71 75 65 72 79 20 69 6e 20 73 71 6c 20 68  e query in sql h
dc20: 61 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 20  as an empty.**  
dc30: 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
dc40: 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
dc50: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
dc60: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
dc70: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
dc80: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
dc90: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
dca0: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
dcb0: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
dcc0: 20 63 68 61 72 20 2a 2a 2a 70 52 65 73 75 6c 74   char ***pResult
dcd0: 2c 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  ,      /* Result
dce0: 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
dcf0: 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20  /.  int *nrow,  
dd00: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
dd10: 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
dd20: 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
dd30: 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d  */.  int *ncolum
dd40: 6e 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  n,         /* Nu
dd50: 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
dd60: 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
dd70: 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
dd80: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 2f  errmsg         /
dd90: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
dda0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
ddb0: 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
ddc0: 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
ddd0: 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
dde0: 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
ddf0: 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
de00: 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 37  g Functions {F17
de10: 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  400}.**.** These
de20: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
de30: 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  rkalikes of the 
de40: 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
de50: 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
de60: 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
de70: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
de80: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
de90: 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
dea0: 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
deb0: 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
dec0: 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
ded0: 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
dee0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
def0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
df00: 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
df10: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
df20: 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
df30: 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
df40: 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
df50: 66 72 65 65 28 29 5d 2e 20 20 20 42 6f 74 68 20  free()].   Both 
df60: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
df70: 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
df80: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
df90: 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
dfa0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
dfb0: 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
dfc0: 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
dfd0: 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
dfe0: 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e  ** In sqlite3_sn
dff0: 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
e000: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
e010: 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
e020: 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
e030: 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
e040: 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
e050: 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
e060: 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
e070: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
e080: 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
e090: 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
e0a0: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
e0b0: 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
e0c0: 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
e0d0: 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
e0e0: 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
e0f0: 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
e100: 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61  tf().  This is a
e110: 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
e120: 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
e130: 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
e140: 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
e150: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
e160: 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65  atibility.  Note
e170: 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
e180: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
e190: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
e1a0: 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
e1b0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
e1c0: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
e1d0: 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
e1e0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
e1f0: 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64  e buffer.  We ad
e200: 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
e210: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
e220: 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
e230: 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
e240: 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
e250: 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
e260: 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
e270: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
e280: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
e290: 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
e2a0: 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
e2b0: 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41  ibility..**.** A
e2c0: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
e2d0: 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
e2e0: 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
e2f0: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
e300: 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
e310: 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
e320: 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
e330: 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
e340: 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
e350: 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
e360: 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
e370: 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
e380: 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
e390: 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
e3a0: 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
e3b0: 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
e3c0: 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
e3d0: 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
e3e0: 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
e3f0: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
e400: 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
e410: 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
e420: 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
e430: 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
e440: 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
e450: 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
e460: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
e470: 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
e480: 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d 61  ual printf forma
e490: 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
e4a0: 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
e4b0: 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
e4c0: 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
e4d0: 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
e4e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
e4f0: 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
e500: 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
e510: 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
e520: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
e530: 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
e540: 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
e550: 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
e560: 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
e570: 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
e580: 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
e590: 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
e5a0: 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
e5b0: 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
e5c0: 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
e5d0: 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
e5e0: 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
e5f0: 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
e600: 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
e610: 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
e620: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f   For example, so
e630: 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 72   some string var
e640: 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74  iable contains t
e650: 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
e660: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
e670: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
e680: 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
e690: 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
e6a0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
e6b0: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
e6c0: 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
e6d0: 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
e6e0: 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
e6f0: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
e700: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
e710: 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
e720: 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
e730: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
e740: 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
e750: 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
e760: 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
e770: 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
e780: 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
e790: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
e7a0: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
e7b0: 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
e7c0: 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
e7d0: 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
e7e0: 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
e7f0: 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
e800: 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
e810: 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
e820: 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
e830: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
e840: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
e850: 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
e860: 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
e870: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
e880: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
e890: 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
e8a0: 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
e8b0: 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
e8c0: 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
e8d0: 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
e8e0: 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
e8f0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
e900: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
e910: 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
e920: 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
e930: 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
e940: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
e950: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
e960: 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
e970: 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
e980: 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
e990: 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68  l rule you.** sh
e9a0: 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73 65 20  ould always use 
e9b0: 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
e9c0: 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
e9d0: 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
e9e0: 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a  ng .** literal..
e9f0: 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74  **.** The %Q opt
ea00: 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
ea10: 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
ea20: 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
ea30: 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
ea40: 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
ea50: 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
ea60: 4f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  Or if the parame
ea70: 74 65 72 20 69 6e 20 74 68 65 20 61 72 67 75 6d  ter in the argum
ea80: 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61  ent.** list is a
ea90: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
eaa0: 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
eab0: 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
eac0: 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a  ithout single.**
ead0: 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
eae0: 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
eaf0: 6f 6e 2e 20 7b 45 4e 44 7d 20 20 53 6f 2c 20 66  on. {END}  So, f
eb00: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
eb10: 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
eb20: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
eb30: 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
eb40: 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
eb50: 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
eb60: 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
eb70: 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
eb80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
eb90: 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
eba0: 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
ebb0: 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
ebc0: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
ebd0: 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
ebe0: 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
ebf0: 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
ec00: 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
ec10: 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
ec20: 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
ec30: 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
ec40: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
ec50: 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f  *.** The "%z" fo
ec60: 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
ec70: 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69  works exactly li
ec80: 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68 65  ke "%s" with the
ec90: 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
eca0: 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
ecb0: 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
ecc0: 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
ecd0: 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
ece0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
ecf0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
ed00: 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20  e input string. 
ed10: 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  {END}.**.** INVA
ed20: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
ed30: 31 37 34 30 33 7d 20 20 54 68 65 20 5b 73 71 6c  17403}  The [sql
ed40: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20  ite3_mprintf()] 
ed50: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70  and [sqlite3_vmp
ed60: 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61  rintf()] interfa
ed70: 63 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ces.**          
ed80: 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 70   return either p
ed90: 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
eda0: 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
edb0: 20 73 74 72 69 6e 67 73 20 68 65 6c 64 20 69 6e   strings held in
edc0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 65  .**           me
edd0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
ede0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
edf0: 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f  oc()] or NULL po
ee00: 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20 20 20 20  inters if.**    
ee10: 20 20 20 20 20 20 20 61 20 63 61 6c 6c 20 74 6f         a call to
ee20: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ee30: 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  ()] fails..**.**
ee40: 20 7b 46 31 37 34 30 36 7d 20 20 54 68 65 20 5b   {F17406}  The [
ee50: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
ee60: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72  ()] interface wr
ee70: 69 74 65 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  ites a zero-term
ee80: 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
ee90: 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67      UTF-8 string
eea0: 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
eeb0: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
eec0: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
eed0: 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
eee0: 20 70 72 6f 76 69 64 65 64 20 74 68 61 74 20 74   provided that t
eef0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
ef00: 65 72 20 69 73 20 67 72 65 61 74 65 72 20 74 68  er is greater th
ef10: 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b  an zero..**.** {
ef20: 46 31 37 34 30 37 7d 20 20 54 68 65 20 5b 73 71  F17407}  The [sq
ef30: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
ef40: 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
ef50: 20 6e 6f 74 20 77 72 69 74 65 73 20 73 6c 6f 74   not writes slot
ef60: 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
ef70: 20 20 69 74 73 20 6f 75 74 70 75 74 20 62 75 66    its output buf
ef80: 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e 64 20  fer (the second 
ef90: 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74 73 69  parameter) outsi
efa0: 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a 20  de the range.** 
efb0: 20 20 20 20 20 20 20 20 20 20 6f 66 20 30 20 74            of 0 t
efc0: 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68 65 72  hrough N-1 (wher
efd0: 65 20 4e 20 69 73 20 74 68 65 20 66 69 72 73 74  e N is the first
efe0: 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 20   parameter).**  
eff0: 20 20 20 20 20 20 20 20 20 72 65 67 61 72 64 6c           regardl
f000: 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e 67 74  ess of the lengt
f010: 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 0a  h of the string.
f020: 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 71  **           req
f030: 75 65 73 74 65 64 20 62 79 20 74 68 65 20 66 6f  uested by the fo
f040: 72 6d 61 74 20 73 70 65 63 69 66 69 63 61 74 69  rmat specificati
f050: 6f 6e 2e 0a 2a 2a 20 20 20 0a 2a 2f 0a 63 68 61  on..**   .*/.cha
f060: 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
f070: 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
f080: 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
f090: 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
f0a0: 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
f0b0: 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
f0c0: 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
f0d0: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
f0e0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
f0f0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
f100: 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
f110: 74 65 6d 20 7b 46 31 37 33 30 30 7d 0a 2a 2a 0a  tem {F17300}.**.
f120: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
f130: 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74  re  uses these t
f140: 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
f150: 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
f160: 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
f170: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
f180: 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
f190: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
f1a0: 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
f1b0: 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
f1c0: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
f1d0: 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
f1e0: 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
f1f0: 77 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  windows VFS uses
f200: 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 20 61   native malloc a
f210: 6e 64 20 66 72 65 65 20 66 6f 72 20 73 6f 6d 65  nd free for some
f220: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
f230: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
f240: 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
f250: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
f260: 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
f270: 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
f280: 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
f290: 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
f2a0: 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
f2b0: 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
f2c0: 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
f2d0: 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
f2e0: 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
f2f0: 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
f300: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
f310: 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74    If the paramet
f320: 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
f330: 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
f340: 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
f350: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
f360: 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
f370: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
f380: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73  .**.** Calling s
f390: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
f3a0: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
f3b0: 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
f3c0: 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
f3d0: 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
f3e0: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
f3f0: 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
f400: 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
f410: 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
f420: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72    The sqlite3_fr
f430: 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
f440: 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
f450: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
f460: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
f470: 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
f480: 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
f490: 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
f4a0: 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
f4b0: 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
f4c0: 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
f4d0: 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
f4e0: 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
f4f0: 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
f500: 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
f510: 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
f520: 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
f530: 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
f540: 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
f550: 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
f560: 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
f570: 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
f580: 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
f590: 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
f5a0: 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
f5b0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
f5c0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
f5d0: 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
f5e0: 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
f5f0: 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
f600: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66 72  () or sqlite3_fr
f610: 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ee()..**.** The 
f620: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
f630: 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
f640: 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
f650: 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
f660: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
f670: 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
f680: 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
f690: 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
f6a0: 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
f6b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
f6c0: 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
f6d0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
f6e0: 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65 20  ameter.  If the 
f6f0: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
f700: 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
f710: 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  oc().** is a NUL
f720: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
f730: 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
f740: 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
f750: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
f760: 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e  alloc(N) where N
f770: 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   is the second p
f780: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
f790: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
f7a0: 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * If the second 
f7b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
f7c0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
f7d0: 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
f7e0: 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
f7f0: 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
f800: 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
f810: 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
f820: 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
f830: 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
f840: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
f850: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
f860: 2a 20 53 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * Sqlite3_reallo
f870: 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
f880: 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
f890: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
f8a0: 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
f8b0: 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
f8c0: 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
f8d0: 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
f8e0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d  ailable..** If M
f8f0: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
f900: 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
f910: 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
f920: 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
f930: 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
f940: 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
f950: 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
f960: 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
f970: 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
f980: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
f990: 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
f9a0: 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
f9b0: 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72  .** If sqlite3_r
f9c0: 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
f9d0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
f9e0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
f9f0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
fa00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f  ..**.** The memo
fa10: 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
fa20: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
fa30: 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
fa40: 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
fa50: 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
fa60: 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
fa70: 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d   boundary. {END}
fa80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
fa90: 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  lt implementatio
faa0: 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65 6d 6f  n.** of the memo
fab0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
fac0: 62 73 79 73 74 65 6d 20 75 73 65 73 20 74 68 65  bsystem uses the
fad0: 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
fae0: 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72 65 65  oc().** and free
faf0: 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  () provided by t
fb00: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
fb10: 62 72 61 72 79 2e 20 7b 46 31 37 33 38 32 7d 20  brary. {F17382} 
fb20: 48 6f 77 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20  However, if .** 
fb30: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
fb40: 65 64 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c  ed with the foll
fb50: 6f 77 69 6e 67 20 43 20 70 72 65 70 72 6f 63 65  owing C preproce
fb60: 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a  ssor macro.**.**
fb70: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51   <blockquote> SQ
fb80: 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45  LITE_MEMORY_SIZE
fb90: 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f 62 6c  =<i>NNN</i> </bl
fba0: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
fbb0: 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  where <i>NNN</i>
fbc0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   is an integer, 
fbd0: 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61  then SQLite crea
fbe0: 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 61  te a static.** a
fbf0: 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74  rray of at least
fc00: 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65   <i>NNN</i> byte
fc10: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73  s in size and us
fc20: 65 20 74 68 61 74 20 61 72 72 61 79 0a 2a 2a 20  e that array.** 
fc30: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
fc40: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
fc50: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
fc60: 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61  {END}  Additiona
fc70: 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  l.** memory allo
fc80: 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 20 6d 61  cator options ma
fc90: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
fca0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
fcb0: 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
fcc0: 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
fcd0: 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
fce0: 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
fcf0: 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
fd00: 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
fd10: 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
fd20: 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
fd30: 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
fd40: 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
fd50: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
fd60: 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
fd70: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
fd80: 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
fd90: 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
fda0: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
fdb0: 74 6f 72 73 20 63 61 6e 20 62 65 0a 2a 2a 20 75  tors can be.** u
fdc0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 77  sed..**.** The w
fdd0: 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
fde0: 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
fdf0: 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
fe00: 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
fe10: 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
fe20: 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
fe30: 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
fe40: 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
fe50: 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
fe60: 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
fe70: 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
fe80: 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
fe90: 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 77 69  he particular wi
fea0: 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
feb0: 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
fec0: 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
fed0: 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
fee0: 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
fef0: 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
ff00: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
ff10: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
ff20: 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
ff30: 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
ff40: 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
ff50: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  NTS:.**.** {F173
ff60: 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  03}  The [sqlite
ff70: 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74  3_malloc(N)] int
ff80: 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
ff90: 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20  ither a pointer 
ffa0: 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  to .**          
ffb0: 20 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f   newly checked-o
ffc0: 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c  ut block of at l
ffd0: 65 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20  east N bytes of 
ffe0: 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
fff0: 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79      that is 8-by
10000 74 65 20 61 6c 69 67 6e 65 64 2c 20 0a 2a 2a 20  te aligned, .** 
10010 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 74 20            or it 
10020 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
10030 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
10040 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75  fulfill the requ
10050 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  est..**.** {F173
10060 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  04}  The [sqlite
10070 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74  3_malloc(N)] int
10080 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
10090 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
100a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20  .**           N 
100b0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  is less than or 
100c0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a  equal to zero..*
100d0 2a 0a 2a 2a 20 7b 46 31 37 33 30 35 7d 20 20 54  *.** {F17305}  T
100e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  he [sqlite3_free
100f0 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (P)] interface r
10100 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70  eleases memory p
10110 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20  reviously.**    
10120 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20         returned 
10130 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
10140 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
10150 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
10160 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b  **           mak
10170 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65  ing it available
10180 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a   for reuse..**.*
10190 2a 20 7b 46 31 37 33 30 36 7d 20 20 41 20 63 61  * {F17306}  A ca
101a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ll to [sqlite3_f
101b0 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20  ree(NULL)] is a 
101c0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
101d0 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 30 7d 20 20  **.** {F17310}  
101e0 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
101f0 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d  e3_realloc(0,N)]
10200 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
10210 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  o a call.**     
10220 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
10230 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a  3_malloc(N)]..**
10240 0a 2a 2a 20 7b 46 31 37 33 31 32 7d 20 20 41 20  .** {F17312}  A 
10250 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
10260 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69  _realloc(P,0)] i
10270 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
10280 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  a call.**       
10290 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f      to [sqlite3_
102a0 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20  free(P)]..**.** 
102b0 7b 46 31 37 33 31 35 7d 20 20 54 68 65 20 53 51  {F17315}  The SQ
102c0 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b  Lite core uses [
102d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
102e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  ], [sqlite3_real
102f0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
10300 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65       and [sqlite
10310 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c  3_free()] for al
10320 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20  l of its memory 
10330 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a  allocation and.*
10340 2a 20 20 20 20 20 20 20 20 20 20 20 64 65 61 6c  *           deal
10350 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
10360 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 38 7d 20 20  **.** {F17318}  
10370 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  The [sqlite3_rea
10380 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72  lloc(P,N)] inter
10390 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
103a0 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  her a pointer.**
103b0 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 61 20             to a 
103c0 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64  block of checked
103d0 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61  -out memory of a
103e0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
103f0 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20  in size.**      
10400 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62       that is 8-b
10410 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20  yte aligned, or 
10420 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
10430 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 31 7d 20 20  **.** {F17321}  
10440 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  When [sqlite3_re
10450 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75  alloc(P,N)] retu
10460 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  rns a non-NULL p
10470 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74  ointer, it first
10480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
10490 70 69 65 73 20 74 68 65 20 66 69 72 73 74 20 4b  pies the first K
104a0 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e   bytes of conten
104b0 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68  t from P into th
104c0 65 20 6e 65 77 6c 79 20 61 6c 6c 6f 63 61 74 65  e newly allocate
104d0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 77  d.**           w
104e0 68 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65  here K is the le
104f0 73 73 6f 72 20 6f 66 20 4e 20 61 6e 64 20 74 68  ssor of N and th
10500 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
10510 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ffer P..**.** {F
10520 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73 71  17322}  When [sq
10530 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
10540 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  N)] returns a no
10550 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
10560 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  it first.**     
10570 20 20 20 20 20 20 72 65 6c 65 61 73 65 73 20 74        releases t
10580 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  he buffer P..**.
10590 2a 2a 20 7b 46 31 37 33 32 33 7d 20 20 57 68 65  ** {F17323}  Whe
105a0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  n [sqlite3_reall
105b0 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73  oc(P,N)] returns
105c0 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66 65   NULL, the buffe
105d0 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  r P is.**       
105e0 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64      not modified
105f0 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a   or released..**
10600 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
10610 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 30 7d 20  .**.** {U17350} 
10620 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
10630 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
10640 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
10650 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
10660 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
10670 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
10680 55 4c 4c 20 6f 72 20 65 6c 73 65 20 61 20 70 6f  ULL or else a po
10690 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 20 66  inter obtained f
106a0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20  rom a prior.**  
106b0 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74           invocat
106c0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
106d0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
106e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
106f0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 20 20 20   that has.**    
10700 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e 20         not been 
10710 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
10720 7b 55 31 37 33 35 31 7d 20 20 54 68 65 20 61 70  {U17351}  The ap
10730 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
10740 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
10750 20 61 6e 79 20 70 61 72 74 20 6f 66 20 0a 2a 2a   any part of .**
10760 20 20 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f             a blo
10770 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
10780 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
10790 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
107a0 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
107b0 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
107c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
107d0 29 5d 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 2a  )]..**.*/.void *
107e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
107f0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
10800 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
10810 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
10820 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
10830 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10840 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
10850 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b  tor Statistics {
10860 46 31 37 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 53 51  F17370}.**.** SQ
10870 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
10880 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
10890 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
108a0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
108b0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
108c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
108d0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
108e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
108f0 6c 6f 63 28 29 5d 0a 2a 2a 20 74 68 65 20 6d 65  loc()].** the me
10900 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10910 73 75 62 73 79 73 74 65 6d 20 69 6e 63 6c 75 64  subsystem includ
10920 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 53 51  ed within the SQ
10930 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  Lite..**.** INVA
10940 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
10950 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69  17371} The [sqli
10960 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
10970 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
10980 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
10990 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
109a0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  es of memory cur
109b0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
109c0 6e 67 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ng .**          
109d0 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
109e0 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20  t freed)..**.** 
109f0 7b 46 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71  {F17373} The [sq
10a00 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
10a10 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
10a20 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
10a30 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20  ximum.**        
10a40 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69    value of [sqli
10a50 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
10a60 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )] .**          
10a70 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 77 61  since the highwa
10a80 74 65 72 20 6d 61 72 6b 20 77 61 73 20 6c 61 73  ter mark was las
10a90 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b  t reset..**.** {
10aa0 46 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75  F17374} The valu
10ab0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
10ac0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
10ad0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  sed()] and.**   
10ae0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
10af0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
10b00 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
10b10 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20  overhead.**     
10b20 20 20 20 20 20 61 64 64 65 64 20 62 79 20 53 51       added by SQ
10b30 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
10b40 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
10b50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10b60 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75  ,.**          bu
10b70 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
10b80 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
10b90 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
10ba0 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20  m library.**    
10bb0 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74        routines t
10bc0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
10bd0 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
10be0 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 37 33 37 35 7d  .** .** {F17375}
10bf0 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68   The memory high
10c00 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
10c10 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
10c20 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20  nt value of.**  
10c30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
10c40 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
10c50 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
10c60 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
10c70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
10c80 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
10c90 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
10ca0 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  .  The value ret
10cb0 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
10cc0 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65    by [sqlite3_me
10cd0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
10ce0 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 77 61  )] is the highwa
10cf0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20  ter mark.**     
10d00 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68       prior to th
10d10 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
10d20 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
10d30 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
10d40 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
10d50 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
10d60 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
10d70 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
10d80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
10d90 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
10da0 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 46 31 37  r Generator {F17
10db0 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  390}.**.** SQLit
10dc0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
10dd0 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
10de0 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
10df0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
10e00 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
10e10 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20  t random ROWIDs 
10e20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
10e30 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
10e40 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
10e50 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
10e60 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
10e70 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52  e ROWID.  The PR
10e80 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
10e90 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
10ea0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
10eb0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
10ec0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
10ed0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
10ee0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 61 74 69 6f  ows.** appliatio
10ef0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
10f00 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
10f10 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
10f20 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74  *.** A call to t
10f30 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
10f40 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
10f50 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
10f60 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68  ffer P..**.** Th
10f70 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
10f80 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
10f90 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
10fa0 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
10fb0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10fc0 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
10fd0 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
10fe0 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
10ff0 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
11000 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
11010 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
11020 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
11030 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62  t..** On all sub
11040 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
11050 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
11060 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
11070 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
11080 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
11090 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
110a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
110b0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
110c0 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ethod..**.** INV
110d0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
110e0 46 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c  F17392} The [sql
110f0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
11100 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,P)] interface 
11110 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f  writes N bytes o
11120 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69  f.**          hi
11130 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
11140 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  o-randomness int
11150 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76  o buffer P..*/.v
11160 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
11170 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
11180 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
11190 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
111a0 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
111b0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ion Callbacks {F
111c0 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  12500}.**.** Thi
111d0 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
111e0 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72  ers a authorizer
111f0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
11200 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
11210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11220 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
11230 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
11240 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74  ment..** The aut
11250 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
11260 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
11270 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
11280 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
11290 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
112a0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
112b0 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
112c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
112d0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
112e0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
112f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
11300 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61  16_v2()].  At va
11310 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
11320 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
11330 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
11340 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
11350 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
11360 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
11370 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
11380 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
11390 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
113a0 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
113b0 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
113c0 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69  ed.  The authori
113d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
113e0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
113f0 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
11400 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
11410 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
11420 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
11430 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
11440 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
11450 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
11460 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
11470 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
11480 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
11490 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
114a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
114b0 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
114c0 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
114d0 20 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72     If the author
114e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
114f0 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
11500 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
11510 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
11520 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
11530 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
11540 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  then [sqlite3_pr
11550 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
11560 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
11570 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
11580 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
11590 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
115a0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
115b0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
115c0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
115d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
115e0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
115f0 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
11600 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e  ted is ok.  When
11610 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
11620 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
11630 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
11640 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
11650 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
11660 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
11670 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
11680 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
11690 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
116a0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
116b0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
116c0 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66 20   is denied.  If 
116d0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
116e0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
116f0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
11700 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
11710 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
11720 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
11730 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11740 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
11750 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
11760 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
11770 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
11780 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
11790 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
117a0 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
117b0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
117c0 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
117d0 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
117e0 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
117f0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
11800 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
11810 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
11820 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
11830 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
11840 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  able..**.** The 
11850 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
11860 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
11870 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
11880 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74  copy of.** the t
11890 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
118a0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
118b0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
118c0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65  nterface..** The
118d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
118e0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
118f0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
11900 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  .** [SQLITE_COPY
11910 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
11920 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
11930 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
11940 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75  tion.** to be au
11950 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68  thorized. The th
11960 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
11970 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  h.** parameters 
11980 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
11990 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
119a0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
119b0 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 61 64 64   contain .** add
119c0 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20  itional details 
119d0 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
119e0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
119f0 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  d..**.** An auth
11a00 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
11a10 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
11a20 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
11a30 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
11a40 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
11a50 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c  usted.** source,
11a60 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
11a70 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
11a80 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ts do not try to
11a90 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20   access data.** 
11aa0 74 68 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f  that they are no
11ab0 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
11ac0 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
11ad0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20  o not try to.** 
11ae0 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
11af0 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
11b00 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
11b10 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
11b20 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
11b30 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
11b40 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
11b50 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
11b60 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
11b70 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
11b80 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
11b90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
11ba0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
11bb0 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
11bc0 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
11bd0 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
11be0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
11bf0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
11c00 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
11c10 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
11c20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
11c30 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
11c40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
11c50 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
11c60 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
11c70 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
11c80 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
11c90 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
11ca0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
11cb0 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
11cc0 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
11cd0 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
11ce0 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
11cf0 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
11d00 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
11d10 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
11d20 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
11d30 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
11d40 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
11d50 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
11d60 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
11d70 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
11d80 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
11d90 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61   Only a single a
11da0 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
11db0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
11dc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11dd0 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
11de0 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
11df0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
11e00 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
11e10 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
11e20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74  call.  Disable t
11e30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
11e40 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
11e50 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
11e60 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
11e70 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
11e80 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  fault..**.** Not
11e90 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
11ea0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
11eb0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
11ec0 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  uring .** [sqlit
11ed0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
11ee0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
11ef0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
11f00 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
11f10 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
11f20 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
11f30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
11f40 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
11f50 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  NTS:.**.** {F125
11f60 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
11f70 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
11f80 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  D,...)] interfac
11f90 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a  e registers a.**
11fa0 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72            author
11fb0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
11fc0 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  th database conn
11fd0 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ection D..**.** 
11fe0 7b 46 31 32 35 30 32 7d 20 54 68 65 20 61 75 74  {F12502} The aut
11ff0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
12000 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
12010 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
12020 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  e.**          be
12030 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 0a  ing compiled.**.
12040 2a 2a 20 7b 46 31 32 35 30 33 7d 20 49 66 20 74  ** {F12503} If t
12050 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
12060 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
12070 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
12080 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
12090 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
120a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
120b0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
120c0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
120d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
120e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
120f0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
12100 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20  at caused.**    
12110 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f 72        the author
12120 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f  izer callback to
12130 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20   run shall fail 
12140 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
12150 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
12160 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  R] error code an
12170 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
12180 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
12190 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 34 7d 20 57  **.** {F12504} W
121a0 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hen the authoriz
121b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
121c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
121d0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
121e0 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63 72  *          descr
121f0 69 62 65 64 20 69 73 20 63 6f 64 65 64 20 6e 6f  ibed is coded no
12200 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  rmally..**.** {F
12210 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20  12505} When the 
12220 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
12230 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
12240 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
12250 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
12260 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
12270 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
12280 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
12290 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
122a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
122b0 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
122c0 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20  l fail.**       
122d0 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49     with an [SQLI
122e0 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
122f0 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f  code and an erro
12300 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
12310 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67        explaining
12320 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20   that access is 
12330 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  denied..**.** {F
12340 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75  12506} If the au
12350 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
12360 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
12370 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
12380 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
12390 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c  allback) is [SQL
123a0 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68  ITE_READ] and th
123b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
123c0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
123d0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
123e0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
123f0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
12400 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
12410 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20  cted to.**      
12420 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c      insert a NUL
12430 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
12440 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
12450 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
12460 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  have.**         
12470 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
12480 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
12490 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  en returned..**.
124a0 2a 2a 20 7b 46 31 32 35 30 37 7d 20 49 66 20 74  ** {F12507} If t
124b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
124c0 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61  de (the 2nd para
124d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
124e0 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  horizer.**      
124f0 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73      callback) is
12500 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20   anything other 
12510 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41  than [SQLITE_REA
12520 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  D], then.**     
12530 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66       a return of
12540 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
12550 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66   has the same ef
12560 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f  fect as [SQLITE_
12570 44 45 4e 59 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46  DENY]. .**.** {F
12580 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74  12510} The first
12590 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
125a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
125b0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
125c0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
125d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
125e0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
125f0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
12600 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  r()] interface..
12610 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 31 7d 20 54  **.** {F12511} T
12620 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
12630 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
12640 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
12650 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  r .**          [
12660 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
12670 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
12680 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61  specifies the pa
12690 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a  rticular action.
126a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62  **          to b
126b0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
126c0 0a 2a 2a 20 7b 46 31 32 35 31 32 7d 20 54 68 65  .** {F12512} The
126d0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
126e0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  ixth parameters 
126f0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
12700 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  are.**          
12710 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
12720 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
12730 74 61 69 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20  tain .**        
12740 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74    additional det
12750 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
12760 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
12770 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  orized..**.** {F
12780 31 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c  12520} Each call
12790 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74   to [sqlite3_set
127a0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f  _authorizer()] o
127b0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
127c0 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65           any pre
127d0 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65  viously installe
127e0 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  d authorizer..**
127f0 0a 2a 2a 20 7b 46 31 32 35 32 31 7d 20 41 20 4e  .** {F12521} A N
12800 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d  ULL authorizer m
12810 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74  eans that no aut
12820 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20  horization.**   
12830 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
12840 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
12850 2a 20 7b 46 31 32 35 32 32 7d 20 54 68 65 20 64  * {F12522} The d
12860 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65  efault authorize
12870 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  r is NULL..*/.in
12880 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
12890 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
128a0 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
128b0 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
128c0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
128d0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
128e0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
128f0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
12900 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
12910 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
12920 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b  r Return Codes {
12930 46 31 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12590}.**.** Th
12940 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
12950 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
12960 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
12970 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
12980 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
12990 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
129a0 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
129b0 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
129c0 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
129d0 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
129e0 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
129f0 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
12a00 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
12a10 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
12a20 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
12a30 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
12a40 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
12a50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
12a60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12a70 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
12a80 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
12a90 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
12aa0 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
12ab0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
12ac0 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
12ad0 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
12ae0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
12af0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
12b00 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
12b10 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20  er Action Codes 
12b20 7b 46 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12550}.**.** T
12b30 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
12b40 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
12b50 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
12b60 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
12b70 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
12b80 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
12b90 6f 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20 53  orizer certain S
12ba0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
12bb0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
12bc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
12bd0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
12be0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
12bf0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
12c00 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
12c10 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
12c20 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
12c30 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
12c40 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
12c50 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
12c60 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
12c70 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
12c80 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
12c90 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
12ca0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
12cb0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a  ation is to be .
12cc0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
12cd0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
12ce0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
12cf0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
12d00 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
12d10 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
12d20 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
12d30 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
12d40 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
12d50 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
12d60 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
12d70 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70  eter.  The 5th p
12d80 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
12d90 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
12da0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
12db0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
12dc0 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
12dd0 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66  p", .** etc.) if
12de0 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68   applicable.  Th
12df0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
12e00 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
12e10 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
12e20 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
12e30 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
12e40 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
12e50 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
12e60 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
12e70 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
12e80 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
12e90 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
12ea0 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f  ctly from .** to
12eb0 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
12ec0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
12ed0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35  TS:.**.** {F1255
12ee0 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  1} The second pa
12ef0 72 61 6d 65 74 65 72 20 74 6f 20 61 6e 20 0a 2a  rameter to an .*
12f00 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
12f10 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
12f20 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
12f30 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6c 77 61  callback is alwa
12f40 79 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  ys an integer.**
12f50 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
12f60 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69  E_COPY | authori
12f70 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74 20 73  zer code] that s
12f80 70 65 63 69 66 69 65 73 20 77 68 61 74 20 61 63  pecifies what ac
12f90 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
12fa0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
12fb0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ized..**.** {F12
12fc0 35 35 32 7d 20 54 68 65 20 33 72 64 20 61 6e 64  552} The 3rd and
12fd0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
12fe0 74 6f 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  to the .**      
12ff0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
13000 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
13010 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c  thorization call
13020 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a  back function].*
13030 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
13040 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
13050 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
13060 6f 6e 20 77 68 69 63 68 20 0a 2a 2a 20 20 20 20  on which .**    
13070 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f        [SQLITE_CO
13080 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  PY | authorizer 
13090 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 73  code] is used as
130a0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
130b0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
130c0 32 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 61  2553} The 5th pa
130d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
130e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
130f0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
13100 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
13110 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65  callback] is the
13120 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   name.**        
13130 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73    of the databas
13140 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69  e (example: "mai
13150 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e  n", "temp", etc.
13160 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
13170 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 34 7d 20  .**.** {F12554} 
13180 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
13190 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  r to the.**     
131a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65       [sqlite3_se
131b0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
131c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
131d0 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a  ck] is the name.
131e0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
131f0 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
13200 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
13210 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
13220 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
13230 20 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74    the access att
13240 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
13250 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
13260 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
13270 66 72 6f 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  from .**        
13280 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20    top-level SQL 
13290 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
132a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
132b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
132c0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
132d0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
132e0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
132f0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
13300 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
13310 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
13320 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
13330 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13340 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
13350 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
13360 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
13370 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
13380 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13390 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
133a0 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
133b0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
133c0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
133d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
133e0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
133f0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
13400 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13410 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13420 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13430 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
13440 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
13450 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
13460 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13470 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13480 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
13490 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
134a0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
134b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
134c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
134d0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
134e0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
134f0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
13500 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
13510 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13520 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
13530 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
13540 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
13550 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
13560 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
13570 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
13580 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
13590 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
135a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
135b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
135c0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
135d0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
135e0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
135f0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
13600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
13610 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
13620 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
13630 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
13640 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
13650 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
13660 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
13670 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
13680 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
13690 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
136a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
136b0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
136c0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
136d0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
136e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
136f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
13700 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
13710 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
13720 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
13730 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
13740 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
13750 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
13760 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
13770 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
13780 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13790 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
137a0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
137b0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
137c0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
137d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
137e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
137f0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
13800 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
13810 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
13820 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13830 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
13840 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
13850 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
13860 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
13870 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13880 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
13890 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
138a0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
138b0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
138c0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
138d0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
138e0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
138f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13900 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
13910 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13920 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
13930 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
13940 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
13950 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
13960 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13970 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
13980 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e         22   /* N
13990 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
139a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
139b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
139c0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
139d0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
139e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
139f0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
13a00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13a10 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
13a20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
13a30 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
13a40 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
13a50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
13a60 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
13a70 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
13a80 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
13a90 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
13aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
13ab0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
13ac0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
13ad0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
13ae0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
13af0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
13b00 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
13b10 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
13b20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
13b30 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
13b40 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
13b50 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
13b60 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
13b70 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
13b80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
13b90 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
13ba0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
13bb0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
13bc0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
13bd0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
13be0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
13bf0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
13c00 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
13c10 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
13c20 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
13c30 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
13c40 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
13c50 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e     /* Function N
13c60 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
13c70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13c80 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
13c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
13ca0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
13cb0 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
13cc0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
13cd0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
13ce0 6e 63 74 69 6f 6e 73 20 7b 46 31 32 32 38 30 7d  nctions {F12280}
13cf0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
13d00 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
13d10 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
13d20 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
13d30 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
13d40 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
13d50 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
13d60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
13d70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
13d80 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
13d90 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
13da0 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
13db0 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
13dc0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
13dd0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
13de0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
13df0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
13e00 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
13e10 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d  k returns a UTF-
13e20 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
13e30 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
13e40 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20   text.** as the 
13e50 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
13e60 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
13e70 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61  .  Additional ca
13e80 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a  llbacks occur.**
13e90 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
13ea0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
13eb0 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
13ec0 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
13ed0 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
13ee0 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
13ef0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
13f00 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a  s the trigger..*
13f10 2a 20 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  * .** The callba
13f20 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
13f30 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
13f40 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
13f50 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
13f60 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
13f70 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70  finishes.  The p
13f80 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
13f90 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
13fa0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
13fb0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
13fc0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
13fd0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
13fe0 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
13ff0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
14000 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   run..**.** The 
14010 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
14020 29 20 41 50 49 20 69 73 20 63 75 72 72 65 6e 74  ) API is current
14030 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  ly considered ex
14040 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a  perimental and.*
14050 2a 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  * is subject to 
14060 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61  change or remova
14070 6c 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  l in a future re
14080 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lease..**.** The
14090 20 74 72 69 67 67 65 72 20 72 65 70 6f 72 74 69   trigger reporti
140a0 6e 67 20 66 65 61 74 75 72 65 20 6f 66 20 74 68  ng feature of th
140b0 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
140c0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a   is considered.*
140d0 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  * experimental a
140e0 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
140f0 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76   change or remov
14100 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
14110 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74 75 72 65  eases..** Future
14120 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
14130 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
14140 64 64 20 6e 65 77 20 74 72 61 63 65 20 63 61 6c  dd new trace cal
14150 6c 62 61 63 6b 20 0a 2a 2a 20 69 6e 76 6f 63 61  lback .** invoca
14160 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  tions..**.** INV
14170 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
14180 46 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c  F12281} The call
14190 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
141a0 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c  gistered by [sql
141b0 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 69 73  ite3_trace()] is
141c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
141d0 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73 74 61  never an SQL sta
141e0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
141f0 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65 20 61  ins to execute a
14200 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nd.**          w
14210 68 65 6e 65 76 65 72 20 61 20 74 72 69 67 67 65  henever a trigge
14220 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66 69 72  r subprogram fir
14230 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72 75 6e  st begins to run
14240 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 32 7d  ..**.** {F12282}
14250 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
14260 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
14270 6f 76 65 72 72 69 64 65 73 20 74 68 65 20 70 72  overrides the pr
14280 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20  eviously.**     
14290 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
142a0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  trace callback..
142b0 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 33 7d 20 41  **.** {F12283} A
142c0 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c   NULL trace call
142d0 62 61 63 6b 20 64 69 73 61 62 6c 65 73 20 74 72  back disables tr
142e0 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  acing..**.** {F1
142f0 32 32 38 34 7d 20 54 68 65 20 66 69 72 73 74 20  2284} The first 
14300 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
14310 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
14320 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20  s a copy of.**  
14330 20 20 20 20 20 20 20 20 74 68 65 20 70 6f 69 6e          the poin
14340 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
14350 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
14360 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
14370 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ()]..**.** {F122
14380 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61  85} The second a
14390 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74  rgument to the t
143a0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
143b0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a   a.**          z
143c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
143d0 54 46 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  TF8 string conta
143e0 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  ining the origin
143f0 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  al text.**      
14400 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73      of the SQL s
14410 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77  tatement as it w
14420 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b  as passed into [
14430 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
14440 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  v2()].**        
14450 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c    or the equival
14460 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63  ent, or an SQL c
14470 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e  omment indicatin
14480 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a  g the beginning.
14490 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
144a0 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
144b0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ram..**.** {F122
144c0 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  87} The callback
144d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
144e0 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ered by [sqlite3
144f0 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69  _profile()] is i
14500 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20  nvoked.**       
14510 20 20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73     as each SQL s
14520 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
14530 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 38  s..**.** {F12288
14540 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
14550 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f  meter to the pro
14560 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  file callback is
14570 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
14580 20 20 20 20 20 20 20 74 68 65 20 33 72 64 20 70         the 3rd p
14590 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
145a0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e  ite3_profile()].
145b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 39 7d 20  .**.** {F12289} 
145c0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
145d0 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
145e0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
145f0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
14600 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
14610 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74 20  F-8 string that 
14620 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d  contains the com
14630 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a  plete text of.**
14640 20 20 20 20 20 20 20 20 20 20 74 68 65 20 53 51            the SQ
14650 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
14660 74 20 77 61 73 20 70 72 6f 63 65 73 73 65 64 20  t was processed 
14670 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
14680 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20  are_v2()].**    
14690 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75        or the equ
146a0 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  ivalent..**.** {
146b0 46 31 32 32 39 30 7d 20 54 68 65 20 74 68 69 72  F12290} The thir
146c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
146d0 68 65 20 70 72 6f 66 69 6c 65 20 20 63 61 6c 6c  he profile  call
146e0 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69 6d  back is an estim
146f0 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ate.**          
14700 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
14710 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20   nanoseconds of 
14720 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20  wall-clock time 
14730 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20  required to.**  
14740 20 20 20 20 20 20 20 20 72 75 6e 20 74 68 65 20          run the 
14750 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 72  SQL statement fr
14760 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e 69  om start to fini
14770 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  sh..*/.void *sql
14780 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
14790 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
147a0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
147b0 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  har*), void*);.v
147c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
147d0 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
147e0 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
147f0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
14800 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
14810 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
14820 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
14830 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
14840 6c 62 61 63 6b 73 20 7b 46 31 32 39 31 30 7d 0a  lbacks {F12910}.
14850 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
14860 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20  ne configures a 
14870 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
14880 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72  n - the.** progr
14890 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74  ess callback - t
148a0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70  hat is invoked p
148b0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
148c0 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69  ng long.** runni
148d0 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ng calls to [sql
148e0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
148f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
14900 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  nd.** [sqlite3_g
14910 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 20 41  et_table()].   A
14920 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
14930 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72  r this .** inter
14940 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
14950 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
14960 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
14970 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ry..**.** If the
14980 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
14990 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
149a0 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 74 69 6f  ero, the opertio
149b0 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
149c0 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
149d0 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
149e0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
149f0 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
14a00 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67   on a GUI dialog
14a10 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   box..**.** INVA
14a20 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
14a30 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62  12911} The callb
14a40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
14a50 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
14a60 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
14a70 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20  dler()].**      
14a80 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70      is invoked p
14a90 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
14aa0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
14ab0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20  calls to.**     
14ac0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74       [sqlite3_st
14ad0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ep()]..**.** {F1
14ae0 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65  2912} The progre
14af0 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ss callback is i
14b00 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
14b10 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a  every N virtual.
14b20 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 68  **          mach
14b30 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65  ine opcodes, whe
14b40 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
14b50 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 0a  nd argument to .
14b60 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
14b70 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73  [sqlite3_progres
14b80 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c  s_handler()] cal
14b90 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65  l that registere
14ba0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
14bb0 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 3c 74 6f  e callback.  <to
14bc0 64 6f 3e 57 68 61 74 20 69 66 20 4e 20 69 73 20  do>What if N is 
14bd0 6c 65 73 73 20 74 68 61 6e 20 31 3f 3c 2f 74 6f  less than 1?</to
14be0 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31  do>.**.** {F1291
14bf0 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  3} The progress 
14c00 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20  callback itself 
14c10 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
14c20 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 20   the third.**   
14c30 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20         argument 
14c40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  to [sqlite3_prog
14c50 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 2e  ress_handler()].
14c60 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 34 7d 20  .**.** {F12914} 
14c70 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
14c80 65 6e 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  ent [sqlite3_pro
14c90 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
14ca0 20 69 73 20 61 0a 2a 2a 2a 20 20 20 20 20 20 20   is a.***       
14cb0 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70    void pointer p
14cc0 61 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f  assed to the pro
14cd0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a  gress callback.*
14ce0 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
14cf0 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74  ion each time it
14d00 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
14d10 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49 66 20 61  ** {F12915} If a
14d20 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
14d30 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74  3_step()] result
14d40 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 0a  s in fewer than.
14d50 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20 6f 70  **          N op
14d60 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 63  codes being exec
14d70 75 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  uted,.**        
14d80 20 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72    then the progr
14d90 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
14da0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 20 7b  never invoked. {
14db0 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32  END}.** .** {F12
14dc0 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20  916} Every call 
14dd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  to [sqlite3_prog
14de0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a  ress_handler()].
14df0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72  **          over
14e00 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 69  writes any previ
14e10 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 20  ously registere 
14e20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
14e30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 37 7d  ..**.** {F12917}
14e40 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
14e50 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
14e60 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e  k is NULL then n
14e70 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20  o progress.**   
14e80 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 69         handler i
14e90 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
14ea0 20 7b 46 31 32 39 31 38 7d 20 49 66 20 74 68 65   {F12918} If the
14eb0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
14ec0 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  ck returns a res
14ed0 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30  ult other than 0
14ee0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
14ef0 20 20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20     the behavior 
14f00 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65 33  is a if [sqlite3
14f10 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68 61  _interrupt()] ha
14f20 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a  d been called..*
14f30 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
14f40 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
14f50 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
14f60 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
14f70 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
14f80 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
14f90 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
14fa0 6e 6e 65 63 74 69 6f 6e 20 7b 46 31 32 37 30 30  nnection {F12700
14fb0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
14fc0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
14fd0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
14fe0 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 0a 2a  ile whose name.*
14ff0 2a 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68  * is given by th
15000 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
15010 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ent..** The file
15020 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
15030 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
15040 55 54 46 2d 38 0a 2a 2a 20 66 6f 72 20 5b 73 71  UTF-8.** for [sq
15050 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e  lite3_open()] an
15060 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  d [sqlite3_open_
15070 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46  v2()] and as UTF
15080 2d 31 36 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  -16.** in the na
15090 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
150a0 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
150b0 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41 6e 20 5b 73  n16()]..** An [s
150c0 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20  qlite3*] handle 
150d0 69 73 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  is usually retur
150e0 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
150f0 65 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72 6f  en.** if an erro
15100 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
15110 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
15120 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
15130 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 6f 63  able.** to alloc
15140 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
15150 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
15160 20 6f 62 6a 65 63 74 2c 20 61 20 4e 55 4c 4c 20   object, a NULL 
15170 77 69 6c 6c 0a 2a 2a 20 62 65 20 77 72 69 74 74  will.** be writt
15180 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
15190 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
151a0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
151b0 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 49  e3] object..** I
151c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
151d0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
151e0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 73 75 63   created).** suc
151f0 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 20  cessfully, then 
15200 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
15210 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
15220 69 73 65 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ise an.** error 
15230 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
15240 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
15250 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
15260 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
15270 36 28 29 5d 20 20 72 6f 75 74 69 6e 65 73 20 63  6()]  routines c
15280 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
15290 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
152a0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
152b0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
152c0 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rror..**.** The 
152d0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
152e0 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
152f0 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  e will be UTF-8 
15300 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  if.** [sqlite3_o
15310 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  pen()] or [sqlit
15320 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73  e3_open_v2()] is
15330 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
15340 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
15350 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
15360 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  f [sqlite3_open1
15370 36 28 29 5d 20 69 73 20 75 73 65 64 2e 0a 2a 2a  6()] is used..**
15380 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
15390 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
153a0 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
153b0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
153c0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
153d0 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  th the [sqlite3*
153e0 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
153f0 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 70  be released by p
15400 61 73 73 69 6e 67 20 69 74 0a 2a 2a 20 74 6f 20  assing it.** to 
15410 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
15420 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
15430 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
15440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
15450 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
15460 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
15470 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ike [sqlite3_ope
15480 6e 28 29 5d 20 0a 2a 2a 20 65 78 63 65 70 74 20  n()] .** except 
15490 74 68 61 74 20 69 74 20 61 63 63 63 65 70 74 73  that it acccepts
154a0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
154b0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
154c0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
154d0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
154e0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
154f0 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
15500 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
15510 62 65 0a 2a 2a 20 6f 6e 65 20 6f 66 3a 0a 2a 2a  be.** one of:.**
15520 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
15530 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52    [SQLITE_OPEN_R
15540 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e  EADONLY].** <li>
15550 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52    [SQLITE_OPEN_R
15560 45 41 44 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69  EADWRITE].** <li
15570 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
15580 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
15590 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
155a0 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ol>.**.**
155b0 20 54 68 65 20 66 69 72 73 74 20 76 61 6c 75 65   The first value
155c0 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62   opens the datab
155d0 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 0a  ase read-only. .
155e0 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
155f0 73 65 20 64 6f 65 73 20 6e 6f 74 20 70 72 65 76  se does not prev
15600 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e  iously exist, an
15610 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
15620 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
15630 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  d option opens.*
15640 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  * the database f
15650 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
15660 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
15670 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 20 6f  le, or reading o
15680 6e 6c 79 20 69 66 0a 2a 2a 20 69 66 20 74 68 65  nly if.** if the
15690 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
156a0 72 6f 74 65 63 74 65 64 2e 20 20 49 6e 20 65 69  rotected.  In ei
156b0 74 68 65 72 20 63 61 73 65 20 74 68 65 20 64 61  ther case the da
156c0 74 61 62 61 73 65 0a 2a 2a 20 6d 75 73 74 20 61  tabase.** must a
156d0 6c 72 65 61 64 79 20 65 78 69 73 74 20 6f 72 20  lready exist or 
156e0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
156f0 72 6e 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  rned.  The third
15700 20 6f 70 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73   option.** opens
15710 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
15720 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
15730 69 74 69 6e 67 20 61 6e 64 20 63 72 65 61 74 65  iting and create
15740 73 20 69 74 20 69 66 20 69 74 20 64 6f 65 73 0a  s it if it does.
15750 2a 2a 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  ** not already e
15760 78 69 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68 69  xist..** The thi
15770 72 64 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 65  rd options is be
15780 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
15790 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 20 5b  lways used for [
157a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
157b0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
157c0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
157d0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
157e0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
157f0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20  3_open_v2()] is 
15800 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
15810 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
15820 68 6f 77 6e 20 61 62 6f 76 65 20 74 68 65 6e 20  hown above then 
15830 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
15840 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
15850 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
15860 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
15870 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 0a  then an private.
15880 2a 2a 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ** in-memory dat
15890 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64  abase is created
158a0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
158b0 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65  ion.  This in-me
158c0 6d 6f 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65  mory.** database
158d0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
158e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
158f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
15900 73 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  sed.  Future.** 
15910 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
15920 65 20 6d 69 67 68 74 20 6d 61 6b 65 20 75 73 65  e might make use
15930 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
15940 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
15950 0a 2a 2a 20 74 68 61 74 20 62 65 67 69 6e 20 77  .** that begin w
15960 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
15970 61 63 74 65 72 2e 20 20 49 74 20 69 73 20 72 65  acter.  It is re
15980 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 0a  commended that .
15990 2a 2a 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  ** when a databa
159a0 73 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 61 6c  se filename real
159b0 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
159c0 74 68 0a 2a 2a 20 22 3a 22 20 74 68 61 74 20 79  th.** ":" that y
159d0 6f 75 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ou prefix the fi
159e0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
159f0 74 68 6e 61 6d 65 20 6c 69 6b 65 20 22 2e 2f 22  thname like "./"
15a00 20 74 6f 0a 2a 2a 20 61 76 6f 69 64 20 61 6d 62   to.** avoid amb
15a10 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66  iguity..**.** If
15a20 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
15a30 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
15a40 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
15a50 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
15a60 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
15a70 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
15a80 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61   This private da
15a90 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
15aa0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
15ab0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
15ac0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
15ad0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
15ae0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
15af0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15b00 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
15b10 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
15b20 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
15b30 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
15b40 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
15b50 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
15b60 65 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  em .** interface
15b70 20 74 68 61 74 20 74 68 65 20 6e 65 77 20 64 61   that the new da
15b80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15b90 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49  n should use.  I
15ba0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
15bb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e  parameter is a N
15bc0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
15bd0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
15be0 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 6f 62  lite3_vfs].** ob
15bf0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
15c00 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 77  .** <b>Note to w
15c10 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
15c20 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
15c30 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
15c40 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
15c50 2a 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * of [sqlite3_op
15c60 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  en()] and [sqlit
15c70 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75  e3_open_v2()] mu
15c80 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
15c90 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
15ca0 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
15cb0 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
15cc0 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
15cd0 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
15ce0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
15cf0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
15d00 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
15d10 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
15d20 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
15d30 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  open()] or [sqli
15d40 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a  te3_open_v2()]..
15d50 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
15d60 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 31 7d  :.**.** {F12701}
15d70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
15d80 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
15d90 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
15da0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
15db0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
15dc0 6e 74 65 72 66 61 63 65 73 20 63 72 65 61 74 65  nterfaces create
15dd0 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
15de0 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
15df0 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  nection] associa
15e00 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ted with.**     
15e10 20 20 20 20 20 74 68 65 20 64 61 74 61 62 61 73       the databas
15e20 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69 6e 20  e file given in 
15e30 74 68 65 69 72 20 66 69 72 73 74 20 70 61 72 61  their first para
15e40 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
15e50 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 61  2702} The filena
15e60 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
15e70 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
15e80 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
15e90 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
15ea0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
15eb0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64  3_open_v2()] and
15ec0 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20   as UTF-16.**   
15ed0 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61         in the na
15ee0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
15ef0 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
15f00 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  n16()]..**.** {F
15f10 31 32 37 30 33 7d 20 41 20 73 75 63 63 65 73 73  12703} A success
15f20 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
15f30 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
15f40 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
15f50 6e 31 36 28 29 5d 2c 20 0a 2a 2a 20 20 20 20 20  n16()], .**     
15f60 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
15f70 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69 74  _open_v2()] writ
15f80 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
15f90 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
15fa0 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
15fb0 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70  ection] into *pp
15fc0 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  Db..**.** {F1270
15fd0 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
15fe0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
15ff0 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
16000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
16010 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
16020 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
16030 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75  rn [SQLITE_OK] u
16040 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20  pon success,.** 
16050 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20 61           or an a
16060 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
16070 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75  r code] on failu
16080 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  re..**.** {F1270
16090 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74  6} The default t
160a0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ext encoding for
160b0 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20   a new database 
160c0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
160d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
160e0 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73  e3_open()] or [s
160f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
16100 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e  ] will be UTF-8.
16110 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 37 7d 20  .**.** {F12707} 
16120 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74  The default text
16130 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20   encoding for a 
16140 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65  new database cre
16150 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
16160 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16170 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62  open16()] will b
16180 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
16190 7b 46 31 32 37 30 39 7d 20 54 68 65 20 5b 73 71  {F12709} The [sq
161a0 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d  lite3_open(F,D)]
161b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71   interface is eq
161c0 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20  uivalent to.**  
161d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
161e0 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30  _open_v2(F,D,G,0
161f0 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 20 70  )] where the G p
16200 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20  arameter is.**  
16210 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
16220 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c  OPEN_READWRITE]|
16230 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
16240 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ATE]..**.** {F12
16250 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 70 61  711} If the G pa
16260 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
16270 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
16280 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
16290 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
162a0 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
162b0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
162c0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
162d0 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20  e is opened.**  
162e0 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61 64          for read
162f0 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ing only..**.** 
16300 7b 46 31 32 37 31 32 7d 20 49 66 20 74 68 65 20  {F12712} If the 
16310 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
16320 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
16330 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
16340 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
16350 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
16360 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
16370 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64 61  ITE] then the da
16380 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
16390 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61  .**          rea
163a0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
163b0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
163c0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c   for reading onl
163d0 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y if the.**     
163e0 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 72 69       file is wri
163f0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
16400 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
16410 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  stem..**.** {F12
16420 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 70 61  713} If the G pa
16430 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
16440 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c  te3_open(v2(F,D,
16450 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a  G,V)] omits the.
16460 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
16470 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
16480 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74  EN_CREATE] and t
16490 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
164a0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
164b0 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
164c0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
164d0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eturned..**.** {
164e0 46 31 32 37 31 34 7d 20 49 66 20 74 68 65 20 47  F12714} If the G
164f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
16500 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46  qlite3_open(v2(F
16510 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e  ,D,G,V)] contain
16520 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
16530 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
16540 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
16550 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
16560 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  e does not.**   
16570 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c         previousl
16580 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 6e  y exist, then an
16590 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
165a0 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a 2a   to create and.*
165b0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 74 69  *          initi
165c0 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62 61  alize the databa
165d0 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  se..**.** {F1271
165e0 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  7} If the filena
165f0 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  me argument to [
16600 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
16610 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
16620 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
16630 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
16640 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d  n_v2()] is ":mem
16650 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70  ory:", then an p
16660 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20  rivate,.**      
16670 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20 69      ephemeral, i
16680 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
16690 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  e is created for
166a0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
166b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
166c0 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45  do>Is SQLITE_OPE
166d0 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f  N_CREATE|SQLITE_
166e0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72  OPEN_READWRITE r
166f0 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20  equired.**      
16700 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f      in sqlite3_o
16710 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e  pen_v2()?</todo>
16720 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 39 7d 20  .**.** {F12719} 
16730 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
16740 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
16750 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
16760 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20   a private,.**  
16770 20 20 20 20 20 20 20 20 65 70 68 65 72 6d 65 72          ephermer
16780 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  al on-disk datab
16790 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
167a0 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted..**         
167b0 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45   <todo>Is SQLITE
167c0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c  _OPEN_CREATE|SQL
167d0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
167e0 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20  TE required.**  
167f0 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74          in sqlit
16800 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74  e3_open_v2()?</t
16810 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  odo>.**.** {F127
16820 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73  21} The [databas
16830 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72  e connection] cr
16840 65 61 74 65 64 20 62 79 20 0a 2a 2a 20 20 20 20  eated by .**    
16850 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
16860 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
16870 20 77 69 6c 6c 20 75 73 65 20 74 68 65 0a 2a 2a   will use the.**
16880 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
16890 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
168a0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
168b0 20 56 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72   V parameter, or
168c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
168d0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
168e0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
168f0 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   V is a NULL poi
16900 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nter..*/.int sql
16910 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
16920 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
16930 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
16940 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
16950 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
16960 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
16970 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
16980 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
16990 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
169a0 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
169b0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
169c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
169d0 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
169e0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
169f0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
16a00 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
16a10 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
16a20 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
16a30 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
16a40 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
16a50 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
16a60 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
16a70 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
16a80 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
16a90 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
16aa0 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
16ab0 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
16ac0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
16ad0 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
16ae0 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
16af0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
16b00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
16b10 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
16b20 65 73 73 61 67 65 73 20 7b 46 31 32 38 30 30 7d  essages {F12800}
16b30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
16b40 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
16b50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
16b60 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53  he numeric.** [S
16b70 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
16b80 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49  t code] or [SQLI
16b90 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
16ba0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
16bb0 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  code].** for the
16bc0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
16bd0 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
16be0 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
16bf0 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74  d.** with [sqlit
16c00 65 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e  e3] handle 'db'.
16c10 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
16c20 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20  call failed but 
16c30 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
16c40 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
16c50 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
16c60 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
16c70 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a  ite3_errcode().*
16c80 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
16c90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
16ca0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
16cb0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
16cc0 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
16cd0 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
16ce0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
16cf0 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
16d00 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 54  ither UTF8 or UT
16d10 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  F16 respectively
16d20 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68  ..** Memory to h
16d30 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
16d40 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
16d50 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
16d60 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
16d70 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
16d80 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 77 69  need to worry wi
16d90 74 68 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  th freeing the r
16da0 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
16db0 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
16dc0 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
16dd0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
16de0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
16df0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
16e00 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
16e10 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
16e20 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ns..**.** INVARI
16e30 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
16e40 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  801} The [sqlite
16e50 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e  3_errcode(D)] in
16e60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
16e70 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  the numeric.**  
16e80 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
16e90 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
16ea0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
16eb0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
16ec0 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
16ed0 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 20  esult code].**  
16ee0 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
16ef0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 66 61  most recently fa
16f00 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63  iled interface c
16f10 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  all associated.*
16f20 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
16f30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16f40 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
16f50 46 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c  F12803} The [sql
16f60 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20  ite3_errmsg(D)] 
16f70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
16f80 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20  msg16(D)].**    
16f90 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
16fa0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
16fb0 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74 68  language text th
16fc0 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20  at describes.** 
16fd0 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72 72           the err
16fe0 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79  or in the mostly
16ff0 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64   recently failed
17000 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c   interface call,
17010 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63  .**          enc
17020 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20 55  oded as either U
17030 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73  TF8 or UTF16 res
17040 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
17050 20 7b 46 31 32 38 30 37 7d 20 54 68 65 20 73 74   {F12807} The st
17060 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
17070 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  y [sqlite3_errms
17080 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  g()] and [sqlite
17090 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a  3_errmsg16()].**
170a0 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61            are va
170b0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  lid until the ne
170c0 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  xt SQLite interf
170d0 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  ace call..**.** 
170e0 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74  {F12808} Calls t
170f0 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74  o API routines t
17100 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72  hat do not retur
17110 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a  n an error code.
17120 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61  **          (exa
17130 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64  mple: [sqlite3_d
17140 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f  ata_count()]) do
17150 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
17160 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f   change the erro
17170 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67  r code or messag
17180 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
17190 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
171a0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
171b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
171c0 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
171d0 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  rrmsg16()]..**.*
171e0 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65 72  * {F12809} Inter
171f0 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e  faces that are n
17200 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ot associated wi
17210 74 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  th a specific.**
17220 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
17230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
17240 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20  (examples:.**   
17250 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
17260 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73  mprintf()] or [s
17270 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
17280 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a  ared_cache()].**
17290 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74            do not
172a0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
172b0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
172c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
172d0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20  te3_errcode()], 
172e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
172f0 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
17300 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a  errmsg16()]..*/.
17310 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
17320 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
17330 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
17340 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
17350 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
17360 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
17370 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
17380 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17390 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
173a0 62 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a 2a  bject {F13000}.*
173b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
173c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
173d0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
173e0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
173f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
17400 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
17410 74 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  t single SQL sta
17420 74 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a 2a  tements.  This.*
17430 2a 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  * object is vari
17440 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
17450 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
17460 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22  ment" or a .** "
17470 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
17480 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
17490 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
174a0 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c  t"..** .** The l
174b0 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
174c0 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
174d0 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
174e0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
174f0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
17500 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
17510 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17520 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
17530 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
17540 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
17550 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
17560 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e   parameters usin
17570 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74  g.**      [sqlit
17580 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
17590 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e  qlite3_bind_* in
175a0 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c  terfaces]..** <l
175b0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
175c0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
175d0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
175e0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
175f0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
17600 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
17610 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
17620 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
17630 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
17640 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
17650 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
17660 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
17670 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
17680 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
17690 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
176a0 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
176b0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
176c0 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
176d0 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
176e0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
176f0 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
17700 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
17710 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
17720 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
17730 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
17740 6d 69 74 73 20 7b 46 31 32 37 36 30 7d 0a 2a 2a  mits {F12760}.**
17750 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
17760 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
17770 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
17780 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
17790 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
177a0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
177b0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
177c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
177d0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
177e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
177f0 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
17800 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
17810 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
17820 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17830 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
17840 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
17850 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
17860 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
17870 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
17880 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
17890 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
178a0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
178b0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
178c0 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75  nstruct.  The fu
178d0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
178e0 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a  he old limit..**
178f0 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c  .** If the new l
17900 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
17910 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
17920 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
17930 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69  d..** For the li
17940 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20  mit category of 
17950 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a  SQLITE_LIMIT_XYZ
17960 20 74 68 65 72 65 20 69 73 20 61 20 68 61 72 64   there is a hard
17970 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20   upper.** bound 
17980 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65  set by a compile
17990 2d 74 69 6d 65 20 43 2d 70 72 65 70 72 6f 63 65  -time C-preproce
179a0 73 73 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53  ss macro named S
179b0 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a  QLITE_MAX_XYZ..*
179c0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
179d0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
179e0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
179f0 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73  _".).** Attempts
17a00 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
17a10 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
17a20 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
17a30 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
17a40 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
17a50 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69   hard upper limi
17a60 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d  t..**.** Run tim
17a70 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
17a80 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
17a90 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
17aa0 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
17ab0 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
17ac0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
17ad0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
17ae0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
17af0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
17b00 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
17b10 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
17b20 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
17b30 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
17b40 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
17b50 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
17b60 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
17b70 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
17b80 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
17b90 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 6a   controlled by j
17ba0 61 76 61 73 63 72 69 70 74 20 61 70 70 6c 69 63  avascript applic
17bb0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
17bc0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 69 6e 74  d.** off the int
17bd0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
17be0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
17bf0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
17c00 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
17c10 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
17c20 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
17c30 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
17c40 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
17c50 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
17c60 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
17c70 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
17c80 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
17c90 61 74 74 61 63 68 2e 20 20 44 65 76 65 6c 6f 70  attach.  Develop
17ca0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
17cb0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
17cc0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17cd0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
17ce0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
17cf0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
17d00 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
17d10 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
17d20 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
17d30 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
17d40 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
17d50 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
17d60 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
17d70 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
17d80 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
17d90 63 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ce is currently 
17da0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
17db0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
17dc0 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61  ubject.** to cha
17dd0 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 77  nge or removal w
17de0 69 74 68 6f 75 74 20 70 72 69 6f 72 20 6e 6f 74  ithout prior not
17df0 69 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ice..**.** INVAR
17e00 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
17e10 32 37 36 32 7d 20 41 20 73 75 63 63 65 73 73 66  2762} A successf
17e20 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
17e30 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
17e40 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20  ] where V is.** 
17e50 20 20 20 20 20 20 20 20 20 70 6f 73 69 74 69 76           positiv
17e60 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
17e70 20 20 20 20 20 20 20 20 20 20 6c 69 6d 69 74 20            limit 
17e80 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63  on the size of c
17e90 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 5b 64  onstruct C in [d
17ea0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17eb0 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20  on] D.**        
17ec0 20 20 74 6f 20 74 68 65 20 6c 65 73 73 6f 72 20    to the lessor 
17ed0 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72  of V and the har
17ee0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  d upper bound on
17ef0 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20 20 20   the size.**    
17f00 20 20 20 20 20 20 6f 66 20 43 20 74 68 61 74 20        of C that 
17f10 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  is set at compil
17f20 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  e-time..**.** {F
17f30 31 32 37 36 34 7d 20 41 20 73 75 63 63 65 73 73  12764} A success
17f40 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
17f50 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
17f60 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 7a 65  )] where V is ze
17f70 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ro.**          c
17f80 68 61 6e 67 65 73 20 74 68 65 20 6c 69 6d 69 74  hanges the limit
17f90 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
17fa0 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 0a 2a  construct C in.*
17fb0 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
17fc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17fd0 20 44 20 74 6f 20 62 65 20 74 68 65 20 68 61 72   D to be the har
17fe0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  d upper bound on
17ff0 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20 20 20   the size.**    
18000 20 20 20 20 20 20 6f 66 20 43 20 74 68 61 74 20        of C that 
18010 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  is set at compil
18020 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  e-time..**.** {F
18030 31 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73  12766} A success
18040 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
18050 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
18060 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65  )] where V is ne
18070 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
18080 20 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74     leaves the st
18090 61 74 65 20 6f 66 20 5b 64 61 74 61 62 61 73 65  ate of [database
180a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75   connection] D u
180b0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20  nchanged..**.** 
180c0 7b 46 31 32 37 36 39 7d 20 41 20 73 75 63 63 65  {F12769} A succe
180d0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
180e0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
180f0 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65  ,V)] returns the
18100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
18110 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20  ue of the limit 
18120 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63  on the size of c
18130 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 0a 2a 2a  onstruct C in.**
18140 20 20 20 20 20 20 20 20 20 20 69 6e 20 5b 64 61            in [da
18150 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18160 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 70  n] D as it was p
18170 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  rior to the call
18180 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18190 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
181a0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
181b0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
181c0 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
181d0 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
181e0 20 7b 46 31 32 37 39 30 7d 0a 2a 2a 20 4b 45 59   {F12790}.** KEY
181f0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
18200 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63  tegory} {limit c
18210 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 20 0a 2a  ategories}.** .*
18220 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
18230 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
18240 20 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64   aspects of a [d
18250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18260 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  on].** that can 
18270 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69  be limited in si
18280 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b  ze by calls to [
18290 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
182a0 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67  ..** The meaning
182b0 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
182c0 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66   limits are as f
182d0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64  ollows:.**.** <d
182e0 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
182f0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
18300 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
18310 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
18320 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 62  y.** string or b
18330 6c 6f 62 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  lob or table row
18340 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  .<dd>.**.** <dt>
18350 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
18360 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
18370 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18380 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
18390 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
183a0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
183b0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
183c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
183d0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
183e0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
183f0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
18400 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
18410 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45  lt set of a SELE
18420 43 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  CT or the maximu
18430 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
18440 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
18450 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
18460 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
18470 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a   clause.</dd>.**
18480 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
18490 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
184a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
184b0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
184c0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
184d0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
184e0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
184f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
18500 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
18510 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18520 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18530 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
18540 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
18550 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
18560 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
18570 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
18580 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
18590 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
185a0 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
185b0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
185c0 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
185d0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
185e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  QL statement.</d
185f0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18600 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
18610 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
18620 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
18630 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
18640 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
18650 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
18660 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
18670 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
18680 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
18690 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65  umber of attache
186a0 64 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64  d databases.</dd
186b0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
186c0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
186d0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
186e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
186f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
18700 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
18710 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20  ent to the LIKE 
18720 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61  or.** GLOB opera
18730 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tors.</dd>.**.**
18740 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18750 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
18760 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
18770 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
18780 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e   of variables in
18790 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
187a0 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65  t that can.** be
187b0 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20   bound.</dd>.** 
187c0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
187d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
187e0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
187f0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
18800 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
18810 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
18820 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
18830 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
18840 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
18850 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
18860 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
18870 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
18880 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
18890 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
188a0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
188b0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
188c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
188d0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
188e0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
188f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
18900 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
18910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
18920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
18930 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
18940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
18950 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18960 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
18970 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
18980 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
18990 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
189a0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
189b0 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   9../*.** CAPI3R
189c0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
189d0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b   SQL Statement {
189e0 46 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f  F13010}.**.** To
189f0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
18a00 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
18a10 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
18a20 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
18a30 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
18a40 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
18a50 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a  routines. .**.**
18a60 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18a70 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b  ent "db" is an [
18a80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18a90 69 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65  ion] .** obtaine
18aa0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63  d from a prior c
18ab0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
18ac0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
18ad0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20  3_open_v2()].** 
18ae0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
18af0 31 36 28 29 5d 2e 20 0a 2a 2a 20 54 68 65 20 73  16()]. .** The s
18b00 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 22  econd argument "
18b10 7a 53 71 6c 22 20 69 73 20 74 68 65 20 73 74 61  zSql" is the sta
18b20 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
18b30 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
18b40 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
18b50 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
18b60 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
18b70 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
18b80 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
18b90 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 73 20  interfaces uses 
18ba0 55 54 46 2d 38 20 61 6e 64 20 73 71 6c 69 74 65  UTF-8 and sqlite
18bb0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
18bc0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
18bd0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
18be0 55 54 46 2d 31 36 2e 20 7b 45 4e 44 7d 0a 2a 2a  UTF-16. {END}.**
18bf0 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65  .** If the nByte
18c00 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
18c10 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20  s.** than zero, 
18c20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
18c30 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  d up to the firs
18c40 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
18c50 72 2e 0a 2a 2a 20 49 66 20 6e 42 79 74 65 20 69  r..** If nByte i
18c60 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
18c70 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
18c80 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18c90 20 0a 2a 2a 20 62 79 74 65 73 20 72 65 61 64 20   .** bytes read 
18ca0 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e  from zSql.  When
18cb0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
18cc0 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
18cd0 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
18ce0 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
18cf0 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
18d00 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
18d10 20 6f 72 20 0a 2a 2a 20 74 68 65 20 6e 42 79 74   or .** the nByt
18d20 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
18d30 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
18d40 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
18d50 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
18d60 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
18d70 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
18d80 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
18d90 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
18da0 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
18db0 61 67 65 20 74 6f 20 62 65 20 68 61 64 20 62 79  age to be had by
18dc0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
18dd0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
18de0 20 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f   .** is equal to
18df0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
18e00 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
18e10 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
18e20 75 64 69 6e 67 3c 2f 69 3e 20 0a 2a 2a 20 74 68  uding</i> .** th
18e30 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
18e40 20 62 79 74 65 73 2e 7b 45 4e 44 7d 0a 2a 2a 0a   bytes.{END}.**.
18e50 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  ** *pzTail is ma
18e60 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
18e70 68 65 20 66 69 72 73 74 20 62 79 74 65 20 70 61  he first byte pa
18e80 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
18e90 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73  e.** first SQL s
18ea0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
18eb0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
18ec0 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73 20  s only compiles 
18ed0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61  the first.** sta
18ee0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
18ef0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
18f00 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77  ft pointing to w
18f10 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75  hat remains.** u
18f20 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
18f30 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
18f40 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
18f50 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
18f60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
18f70 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
18f80 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
18f90 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72  te3_step()].  Or
18fa0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
18fb0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
18fc0 73 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c  s.** set to NULL
18fd0 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20  .  If the input 
18fe0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
18ff0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
19000 75 74 0a 2a 2a 20 69 73 20 61 6e 64 20 65 6d 70  ut.** is and emp
19010 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ty string or a c
19020 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
19030 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
19040 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31 38 7d  ULL..** {U13018}
19050 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
19060 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
19070 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
19080 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ng the.** compil
19090 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
190a0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
190b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
190c0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
190d0 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
190e0 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
190f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
19100 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
19110 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f  ise an .** [erro
19120 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
19130 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
19140 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19150 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
19160 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
19170 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
19180 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
19190 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
191a0 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
191b0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
191c0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
191d0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
191e0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
191f0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
19200 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65  raged..** In the
19210 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
19220 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
19230 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
19240 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
19250 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
19260 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
19270 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
19280 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
19290 20 74 65 78 74 2e 20 7b 45 4e 44 7d 20 54 68 69   text. {END} Thi
192a0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
192b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
192c0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
192d0 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e 74  have a different
192e0 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a  ly in two ways:.
192f0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
19300 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  i>.** If the dat
19310 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
19320 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
19330 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
19340 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
19350 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
19360 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
19370 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
19380 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
19390 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
193a0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
193b0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
193c0 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 6d  n.  If the schem
193d0 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e  a has changed in
193e0 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d  .** a way that m
193f0 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65  akes the stateme
19400 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c  nt no longer val
19410 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  id, [sqlite3_ste
19420 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a  p()] will still.
19430 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
19440 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20  E_SCHEMA].  But 
19450 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63  unlike the legac
19460 79 20 62 65 68 61 76 69 6f 72 2c 20 0a 2a 2a 20  y behavior, .** 
19470 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
19480 69 73 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  is now a fatal e
19490 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 0a 2a  rror.  Calling.*
194a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
194b0 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
194c0 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
194d0 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
194e0 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
194f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
19500 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
19510 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73  t.** of the pars
19520 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72  ing error that r
19530 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
19540 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
19550 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 3c 2f  urn. {END}.** </
19560 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
19570 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20  * When an error 
19580 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c  occurs, .** [sql
19590 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
195a0 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
195b0 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a  the detailed .**
195c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
195d0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
195e0 72 20 63 6f 64 65 73 5d 2e 20 0a 2a 2a 20 54 68  r codes]. .** Th
195f0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
19600 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69  r was that [sqli
19610 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
19620 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
19630 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49  generic.** [SQLI
19640 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
19650 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f   code and you wo
19660 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
19670 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
19680 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
19690 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  set()] in order 
196a0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
196b0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
196c0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20  the problem..** 
196d0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
196e0 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 73  epare interfaces
196f0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
19700 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
19710 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75  error is.** retu
19720 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
19730 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
19740 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ol>.**.** INVARI
19750 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
19760 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  011} The [sqlite
19770 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71  3_prepare(db,zSq
19780 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20  l,...)] and.**  
19790 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
197a0 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
197b0 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  Sql,...)] interf
197c0 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74  aces interpret t
197d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
197e0 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71  ext in their zSq
197f0 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55  l parameter as U
19800 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  TF-8..**.** {F13
19810 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  012} The [sqlite
19820 33 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a  3_prepare16(db,z
19830 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
19840 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
19850 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
19860 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
19870 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
19880 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
19890 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
198a0 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
198b0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
198c0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
198d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  er..**.** {F1301
198e0 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  3} If the nByte 
198f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
19900 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19910 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e  db,zSql,nByte,..
19920 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
19930 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
19940 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
19950 72 6f 2c 20 74 68 65 6e 20 53 51 4c 20 74 65 78  ro, then SQL tex
19960 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  t is.**         
19970 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20   read from zSql 
19980 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
19990 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
199a0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  minator..**.** {
199b0 46 31 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e  F13014} If the n
199c0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
199d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
199e0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
199f0 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  te,...)].**     
19a00 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72       and its var
19a10 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67  iants is non-neg
19a20 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d  ative, then at m
19a30 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65 73  ost nBytes bytes
19a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
19a50 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66 72   text is read fr
19a60 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  om zSql..**.** {
19a70 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69  F13015} In [sqli
19a80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
19a90 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69  b,zSql,N,P,pzTai
19aa0 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  l)] and its vari
19ab0 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ants.**         
19ac0 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70   if the zSql inp
19ad0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
19ae0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53   more than one S
19af0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
19b00 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54           and pzT
19b10 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ail is not NULL,
19b20 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
19b30 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
19b40 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
19b50 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73    first byte pas
19b60 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
19b70 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
19b80 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a  ment in zSql..**
19b90 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
19ba0 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69  What does *pzTai
19bb0 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68  l point to if th
19bc0 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65  ere is one state
19bd0 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  ment?</todo>.**.
19be0 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73 75  ** {F13016} A su
19bf0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
19c00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19c10 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70  e_v2(db,zSql,N,p
19c20 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  pStmt,...)].**  
19c30 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f          or one o
19c40 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 77  f its variants w
19c50 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74  rites into *ppSt
19c60 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  mt a pointer to 
19c70 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
19c80 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
19c90 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e  ement] or a poin
19ca0 74 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20  ter to NULL.**  
19cb0 20 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c 20          if zSql 
19cc0 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67  contains nothing
19cd0 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
19ce0 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e  espace or commen
19cf0 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  ts. .**.** {F130
19d00 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
19d10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
19d20 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73  nterface and its
19d30 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
19d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
19d50 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61  LITE_OK] or an a
19d60 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
19d70 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69  r code] upon fai
19d80 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  lure..**.** {F13
19d90 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c  021} Before [sql
19da0 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
19db0 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d  zSql,nByte,ppStm
19dc0 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74  t,pzTail)] or it
19dd0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  s.**          va
19de0 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61  riants returns a
19df0 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c  n error (any val
19e00 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
19e10 51 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20 20  QLITE_OK]).**   
19e20 20 20 20 20 20 20 20 69 74 20 66 69 72 73 74 20         it first 
19e30 73 65 74 73 20 2a 70 70 53 74 6d 74 20 74 6f 20  sets *ppStmt to 
19e40 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
19e50 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
19e60 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
19e70 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
19e80 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
19e90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
19ea0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
19eb0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
19ec0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
19ed0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
19ee0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
19ef0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
19f00 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
19f10 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
19f20 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
19f30 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
19f40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
19f50 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
19f60 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
19f70 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
19f80 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
19f90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
19fa0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
19fb0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
19fc0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
19fd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
19fe0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
19ff0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1a000 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1a010 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1a020 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1a030 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1a040 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1a050 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1a060 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1a070 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1a080 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1a090 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1a0a0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1a0b0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1a0c0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1a0d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1a0e0 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
1a0f0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1a100 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1a110 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1a120 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
1a130 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1a140 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
1a150 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1a160 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1a170 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1a180 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1a190 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1a1a0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1a1b0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1a1c0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1a1d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
1a1e0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1a1f0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1a200 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1a210 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1a220 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1a230 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1a240 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1a250 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1a260 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1a270 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1a280 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1a290 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1a2a0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1a2b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1a2c0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1a2d0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1a2e0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1a2f0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1a300 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1a310 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1a320 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1a330 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1a340 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1a350 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1a360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a  ../*.** CAPIREF:
1a370 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
1a380 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30  ement SQL {F1310
1a390 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0}.**.** This in
1a3a0 74 65 72 65 66 61 63 65 20 63 61 6e 20 62 65 20  tereface can be 
1a3b0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
1a3c0 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
1a3d0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
1a3e0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
1a3f0 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
1a400 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1a410 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1a420 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31  S:.**.** {F13101
1a430 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
1a440 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
1a450 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20  ssed as .**     
1a460 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75       the an argu
1a470 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1a480 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
1a490 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  iled.**         
1a4a0 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1a4b0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1a4c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1a4d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a4e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1a4f0 76 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  v2()],.**       
1a500 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
1a510 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e  _sql()] function
1a520 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1a530 65 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20 20  er to a.**      
1a540 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
1a550 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  ted string conta
1a560 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65  ining a UTF-8 re
1a570 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ndering.**      
1a580 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69      of the origi
1a590 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  nal SQL statemen
1a5a0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 32  t..**.** {F13102
1a5b0 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
1a5c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
1a5d0 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20  ssed as .**     
1a5e0 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75       the an argu
1a5f0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1a600 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
1a610 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  iled.**         
1a620 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1a630 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1a640 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
1a650 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1a660 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
1a670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a680 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
1a690 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
1a6a0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1a6b0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 33  r..**.** {F13103
1a6c0 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74  } The string ret
1a6d0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1a6e0 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c  3_sql(S)] is val
1a6f0 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20  id until the.** 
1a700 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
1a710 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1a720 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  is deleted using
1a730 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1a740 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ze(S)]..*/.const
1a750 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1a760 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
1a770 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1a780 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d  CAPI3REF:  Dynam
1a790 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
1a7a0 75 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35 30  ue Object  {F150
1a7b0 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
1a7c0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1a7d0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1a7e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1a7f0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1a800 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1a810 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1a820 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1a830 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1a840 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1a850 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1a860 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ble..** SQLite u
1a870 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
1a880 6e 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ng for the value
1a890 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 0a 2a  s it stores.  .*
1a8a0 2a 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20  * Values stored 
1a8b0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
1a8c0 20 6f 62 6a 65 63 74 73 20 63 61 6e 20 62 65 0a   objects can be.
1a8d0 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  ** be integers, 
1a8e0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
1a8f0 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
1a900 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
1a910 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
1a920 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
1a930 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
1a940 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
1a950 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
1a960 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
1a970 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
1a980 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
1a990 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
1a9a0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
1a9b0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
1a9c0 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
1a9d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1a9e0 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
1a9f0 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
1aa00 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
1aa10 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
1aa20 63 69 66 69 65 73 20 0a 2a 2a 20 77 68 65 74 68  cifies .** wheth
1aa30 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
1aa40 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
1aa50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1aa60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
1aa70 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
1aa80 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
1aa90 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
1aaa0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
1aab0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e  x is held.  A in
1aac0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
1aad0 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
1aae0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1aaf0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
1ab00 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
1ab10 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
1ab20 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1ab30 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
1ab40 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
1ab50 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
1ab60 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
1ab70 69 74 68 20 53 51 4c 49 54 45 5f 54 48 52 45 41  ith SQLITE_THREA
1ab80 44 53 41 46 45 3d 30 20 61 6e 64 20 77 69 74 68  DSAFE=0 and with
1ab90 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1aba0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
1abb0 67 20 30 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  g 0).** then the
1abc0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1abd0 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
1abe0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1abf0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1ac00 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1ac10 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 0a  and they can be.
1ac20 2a 2a 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  ** used intercha
1ac30 6e 67 61 62 6c 65 2e 20 20 48 6f 77 65 76 65 72  ngable.  However
1ac40 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  , for maximum co
1ac50 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
1ac60 74 0a 2a 2a 20 69 73 20 72 65 63 6f 6d 6d 65 6e  t.** is recommen
1ac70 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
1ac80 74 69 6f 6e 73 20 6d 61 6b 65 20 74 68 65 20 64  tions make the d
1ac90 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
1aca0 65 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 70 72  en.** between pr
1acb0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1acc0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1acd0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
1ace0 65 6e 20 69 66 0a 2a 2a 20 74 68 65 79 20 61 72  en if.** they ar
1acf0 65 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 65  e single threade
1ad00 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1ad10 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ad20 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
1ad30 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
1ad40 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
1ad50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
1ad60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1ad70 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1ad80 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
1ad90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
1ada0 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
1adb0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
1adc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
1add0 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
1ade0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
1adf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1ae00 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
1ae10 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
1ae20 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
1ae30 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
1ae40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
1ae50 75 65 28 29 5d 2e 20 20 41 6c 6c 20 6f 74 68 65  ue()].  All othe
1ae60 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
1ae70 74 68 61 74 20 75 73 65 20 73 71 6c 69 74 65 33  that use sqlite3
1ae80 5f 76 61 6c 75 65 20 72 65 71 75 69 72 65 20 70  _value require p
1ae90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1aea0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
1aeb0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1aec0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
1aed0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
1aee0 33 52 45 46 3a 20 20 53 51 4c 20 46 75 6e 63 74  3REF:  SQL Funct
1aef0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
1af00 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a  ct {F16001}.**.*
1af10 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
1af20 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
1af30 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
1af40 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
1af50 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
1af60 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f  xt object.  A po
1af70 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
1af80 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20 6f  te3_context.** o
1af90 62 6a 65 63 74 20 69 73 20 61 6c 77 61 79 73 20  bject is always 
1afa0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1afb0 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  to application-d
1afc0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1afd0 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ions..*/.typedef
1afe0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1aff0 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
1b000 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
1b010 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69  CAPI3REF:  Bindi
1b020 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
1b030 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
1b040 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F13500}.**.** 
1b050 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e  In the SQL strin
1b060 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  gs input to [sql
1b070 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b080 29 5d 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76 61  )] and its.** va
1b090 72 69 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c 73  riants, literals
1b0a0 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 20   may be replace 
1b0b0 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69  by a parameter i
1b0c0 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 73  n one.** of thes
1b0d0 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  e forms:.**.** <
1b0e0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
1b0f0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
1b100 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
1b110 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
1b120 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
1b130 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
1b140 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
1b150 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
1b160 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
1b170 61 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c 70 68 61  al,.** VVV alpha
1b180 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74  -numeric paramet
1b190 65 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  er name..** The 
1b1a0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20  values of these 
1b1b0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
1b1c0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
1b1d0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 0a 2a  rameter names".*
1b1e0 2a 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  * or "SQL parame
1b1f0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
1b200 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
1b210 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1b220 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
1b230 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
1b240 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1b250 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
1b260 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1b270 20 61 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61 20   always.** is a 
1b280 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1b290 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1b2a0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
1b2b0 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
1b2c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1b2d0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 54 68  its variants. Th
1b2e0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
1b2f0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1b300 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  x of the paramet
1b310 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 54 68  er to be set. Th
1b320 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d  e.** first param
1b330 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
1b340 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68  x of 1.  When th
1b350 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
1b360 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
1b370 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
1b380 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
1b390 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
1b3a0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
1b3b0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
1b3c0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
1b3d0 63 65 2e 20 0a 2a 2a 20 54 68 65 20 69 6e 64 65  ce. .** The inde
1b3e0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
1b3f0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
1b400 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
1b410 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
1b420 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1b430 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  e()] API if desi
1b440 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a  red.  The index.
1b450 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
1b460 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
1b470 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
1b480 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d   The NNN value m
1b490 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
1b4a0 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65   and the compile
1b4b0 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74  -time.** paramet
1b4c0 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41  er SQLITE_MAX_VA
1b4d0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64  RIABLE_NUMBER (d
1b4e0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
1b4f0 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  9)..**.** The th
1b500 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
1b510 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
1b520 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
1b530 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f  er..**.** In tho
1b540 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  se.** routines t
1b550 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
1b560 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
1b570 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d  value is the num
1b580 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1b590 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
1b5a0 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
1b5b0 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
1b5c0 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
1b5d0 74 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68  tes</u>.** in th
1b5e0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
1b5f0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1b600 63 74 65 72 73 2e 20 0a 2a 2a 20 49 66 20 74 68  cters. .** If th
1b610 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1b620 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
1b630 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
1b640 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e  e string is.** n
1b650 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
1b660 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
1b670 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
1b680 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
1b690 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1b6a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
1b6b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1b6c0 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
1b6d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1b6e0 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
1b6f0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
1b700 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
1b710 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
1b720 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
1b730 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49  ished with it. I
1b740 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1b750 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
1b760 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
1b770 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
1b780 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
1b790 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
1b7a0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
1b7b0 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
1b7c0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
1b7d0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
1b7e0 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  freed..** If the
1b7f0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1b800 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
1b810 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
1b820 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
1b830 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
1b840 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
1b850 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
1b860 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
1b870 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1b880 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
1b890 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rns..**.** The s
1b8a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1b8b0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
1b8c0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
1b8d0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
1b8e0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
1b8f0 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f  eros.  A zeroblo
1b900 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
1b910 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
1b920 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
1b930 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73  ger to hold it s
1b940 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
1b950 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
1b960 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
1b970 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
1b980 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d 68 6f  erve as place-ho
1b990 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
1b9a0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
1b9b0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
1b9c0 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  n using .** [sql
1b9d0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
1b9e0 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20   increment BLOB 
1b9f0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20 41  I/O] routines. A
1ba00 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c   negative.** val
1ba10 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
1ba20 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
1ba30 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1ba40 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  B..**.** The sql
1ba50 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1ba60 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
1ba70 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b  alled after.** [
1ba80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ba90 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76  v2()] (and its v
1baa0 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c  ariants) or [sql
1bab0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e  ite3_reset()] an
1bac0 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c  d.** before [sql
1bad0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1bae0 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f   Bindings are no
1baf0 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
1bb00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1bb10 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55  )] routine..** U
1bb20 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
1bb30 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
1bb40 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
1bb50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1bb60 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1bb70 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
1bb80 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
1bb90 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f  f.** anything go
1bba0 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49  es wrong.  [SQLI
1bbb0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
1bbc0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
1bbd0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
1bbe0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
1bbf0 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
1bc00 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1bc10 6d 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a  malloc fails..**
1bc20 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
1bc30 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
1bc40 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74  ed if these rout
1bc50 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
1bc60 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20  on a.** virtual 
1bc70 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20  machine that is 
1bc80 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20  the wrong state 
1bc90 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72  or which has alr
1bca0 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69  eady been finali
1bcb0 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f  zed..** Detectio
1bcc0 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75  n of misuse is u
1bcd0 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c  nreliable.  Appl
1bce0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
1bcf0 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  not depend.** on
1bd00 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72   SQLITE_MISUSE r
1bd10 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f  eturns.  SQLITE_
1bd20 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64  MISUSE is intend
1bd30 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61  ed to indicate a
1bd40 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f  .** a logic erro
1bd50 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61  r in the applica
1bd60 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65  tion.  Future ve
1bd70 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1bd80 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20   might.** panic 
1bd90 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75  rather than retu
1bda0 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
1bdb0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1bdc0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1bdd0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1bde0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1bdf0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1be00 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
1be10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1be20 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1be30 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1be40 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 36  S:.**.** {F13506
1be50 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  } The [sqlite3_p
1be60 72 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61  repare | SQL sta
1be70 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d  tement compiler]
1be80 20 72 65 63 6f 67 6e 69 7a 65 73 0a 2a 2a 20 20   recognizes.**  
1be90 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 73 20 6f          tokens o
1bea0 66 20 74 68 65 20 66 6f 72 6d 73 20 22 3f 22 2c  f the forms "?",
1beb0 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c   "?NNN", "$VVV",
1bec0 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56   ":VVV", and "@V
1bed0 56 56 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  VV".**          
1bee0 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  as SQL parameter
1bef0 73 2c 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20  s, where NNN is 
1bf00 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
1bf10 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20  one or more.**  
1bf20 20 20 20 20 20 20 20 20 64 69 67 69 74 73 20 61          digits a
1bf30 6e 64 20 77 68 65 72 65 20 56 56 56 20 69 73 20  nd where VVV is 
1bf40 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
1bf50 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a 2a 20  one or more .** 
1bf60 20 20 20 20 20 20 20 20 20 61 6c 70 68 61 6e 75           alphanu
1bf70 6d 65 72 69 63 20 63 68 61 72 61 63 74 65 72 73  meric characters
1bf80 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61   or "::" optiona
1bf90 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 0a  lly followed by.
1bfa0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 73 74  **          a st
1bfb0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
1bfc0 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f  no spaces and co
1bfd0 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70  ntained within p
1bfe0 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a  arentheses..**.*
1bff0 2a 20 7b 46 31 33 35 30 39 7d 20 54 68 65 20 69  * {F13509} The i
1c000 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20  nitial value of 
1c010 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
1c020 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1c030 7b 46 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64  {F13512} The ind
1c040 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c  ex of an "?" SQL
1c050 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
1c060 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
1c070 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61  e.**          la
1c080 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53  rgest index of S
1c090 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
1c0a0 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69  the left, or 1 i
1c0b0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
1c0c0 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66  e "?" is the lef
1c0d0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
1c0e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ter..**.** {F135
1c0f0 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  15} The index of
1c100 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70   an "?NNN" SQL p
1c110 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
1c120 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a  integer NNN..**.
1c130 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54 68 65 20  ** {F13518} The 
1c140 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56  index of an ":VV
1c150 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22  V", "$VVV", or "
1c160 40 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65  @VVV" SQL parame
1c170 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ter is.**       
1c180 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 74     the same as t
1c190 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74  he index of left
1c1a0 6d 6f 73 74 20 6f 63 63 75 72 61 6e 63 65 73 20  most occurances 
1c1b0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  of the same.**  
1c1c0 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
1c1d0 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74  r, or one more t
1c1e0 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20  han the largest 
1c1f0 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a  index over all.*
1c200 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
1c210 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66  eters to the lef
1c220 74 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65  t if this is the
1c230 20 66 69 72 73 74 20 6f 63 63 75 72 72 61 6e 63   first occurranc
1c240 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
1c250 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c   this parameter,
1c260 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 73   or 1 if this is
1c270 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61   the leftmost pa
1c280 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
1c290 46 31 33 35 32 31 7d 20 54 68 65 20 5b 73 71 6c  F13521} The [sql
1c2a0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53  ite3_prepare | S
1c2b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
1c2c0 70 69 6c 65 72 5d 20 66 61 69 6c 20 77 69 74 68  piler] fail with
1c2d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
1c2e0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 65  [SQLITE_RANGE] e
1c2f0 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65  rror if the inde
1c300 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
1c310 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
1c320 20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31    is less than 1
1c330 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
1c340 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
1c350 41 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a 2a 2a 0a  ABLE_NUMBER..**.
1c360 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43 61 6c 6c  ** {F13524} Call
1c370 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1c380 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1c390 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e  3_bind(S,N,V,...
1c3a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1c3b0 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c  ssociate the val
1c3c0 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51  ue V with all SQ
1c3d0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76  L parameters hav
1c3e0 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ing an.**       
1c3f0 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e     index of N in
1c400 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1c410 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
1c420 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43 61 6c 6c  ** {F13527} Call
1c430 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1c440 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1c450 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d  3_bind(S,N,...)]
1c460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
1c470 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c  rride prior call
1c480 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
1c490 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20  values of S and 
1c4a0 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 30  N..**.** {F13530
1c4b0 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62  } Bindings estab
1c4c0 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74  lished by [sqlit
1c4d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
1c4e0 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e  qlite3_bind(S,..
1c4f0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1c500 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63  persist across c
1c510 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1c520 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a  _reset(S)]..**.*
1c530 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e 20 63 61  * {F13533} In ca
1c540 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1c550 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
1c560 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
1c570 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
1c580 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
1c590 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
1c5a0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1c5b0 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1c5c0 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
1c5d0 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20  the first L.**  
1c5e0 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66          bytes of
1c5f0 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 72   the blob or str
1c600 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
1c610 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20  y V, when L.**  
1c620 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e          is non-n
1c630 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
1c640 46 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73  F13536} In calls
1c650 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1c660 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
1c670 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1c680 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1c690 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1c6a0 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
1c6b0 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20  characters.**   
1c6c0 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68         from V th
1c6d0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
1c6e0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77  zero character w
1c6f0 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76  hen L is negativ
1c700 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 39  e..**.** {F13539
1c710 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1c720 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1c730 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
1c740 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c750 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
1c760 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
1c770 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c780 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
1c790 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
1c7a0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a   is the special.
1c7b0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73  **          cons
1c7c0 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
1c7d0 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73  TIC], SQLite ass
1c7e0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61  umes that the va
1c7f0 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20  lue V.**        
1c800 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61    is held in sta
1c810 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  tic unmanaged sp
1c820 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f  ace that will no
1c830 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20  t change.**     
1c840 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20       during the 
1c850 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
1c860 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  binding..**.** {
1c870 46 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73  F13542} In calls
1c880 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1c890 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
1c8a0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
1c8b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1c8c0 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
1c8d0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1c8e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c8f0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
1c900 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
1c910 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
1c920 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
1c930 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
1c940 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73  he routine makes
1c950 20 61 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   a .**          
1c960 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1c970 56 20 76 61 6c 75 65 20 62 65 66 6f 72 65 20 69  V value before i
1c980 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
1c990 20 7b 46 31 33 35 34 35 7d 20 49 6e 20 63 61 6c   {F13545} In cal
1c9a0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1c9b0 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
1c9c0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
1c9d0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1c9e0 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
1c9f0 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1ca00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1ca10 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1ca20 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f  ] when D is a po
1ca30 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  inter to.**     
1ca40 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c       a function,
1ca50 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
1ca60 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f  that function to
1ca70 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
1ca80 20 20 20 20 20 20 20 20 20 56 20 76 61 6c 75 65           V value
1ca90 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1caa0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
1cab0 20 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20   V value..**.** 
1cac0 7b 46 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c  {F13548} In call
1cad0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1cae0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c  nd_zeroblob(S,N,
1caf0 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20  V,L)] the value 
1cb00 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  bound.**        
1cb10 20 20 69 73 20 61 20 62 6c 6f 62 20 6f 66 20 4c    is a blob of L
1cb20 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72   bytes, or a zer
1cb30 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 66  o-length blob if
1cb40 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a   L is negative..
1cb50 2a 2a 0a 2a 2a 20 7b 46 31 33 35 35 31 7d 20 49  **.** {F13551} I
1cb60 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
1cb70 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53  te3_bind_value(S
1cb80 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67  ,N,V)] the V arg
1cb90 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20  ument may.**    
1cba0 20 20 20 20 20 20 62 65 20 65 69 74 68 65 72 20        be either 
1cbb0 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  a [protected sql
1cbc0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
1cbd0 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20  ct or an.**     
1cbe0 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65       [unprotecte
1cbf0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
1cc00 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20   object..*/.int 
1cc10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1cc20 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1cc30 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
1cc40 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1cc50 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1cc60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
1cc70 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
1cc80 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
1cc90 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1cca0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
1ccb0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
1ccc0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1ccd0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
1cce0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
1ccf0 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
1cd00 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
1cd10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1cd20 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
1cd30 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
1cd40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1cd50 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
1cd60 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
1cd70 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1cd80 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
1cd90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1cda0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1cdb0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1cdc0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1cdd0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
1cde0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1cdf0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
1ce00 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1ce10 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
1ce20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1ce30 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
1ce40 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
1ce50 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
1ce60 74 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a  ters {F13600}.**
1ce70 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1ce80 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1ce90 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
1cea0 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
1ceb0 73 0a 2a 2a 20 69 6e 20 61 20 70 72 65 70 61 72  s.** in a prepar
1cec0 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53  ed statement.  S
1ced0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
1cee0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
1cef0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
1cf00 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
1cf10 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
1cf20 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
1cf30 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f  place-holders fo
1cf40 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
1cf50 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1cf60 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
1cf70 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1cf80 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
1cf90 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  me..**.** This r
1cfa0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
1cfb0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
1cfc0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
1cfd0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 46   parameter..** F
1cfe0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
1cff0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
1d000 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
1d010 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  o the number of.
1d020 2a 2a 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  ** unique parame
1d030 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
1d040 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
1d050 20 61 72 65 20 75 73 65 64 2c 20 74 68 65 72 65   are used, there
1d060 20 6d 61 79 0a 2a 2a 20 62 65 20 67 61 70 73 20   may.** be gaps 
1d070 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a  in the list..**.
1d080 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1d090 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1d0a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1d0b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1d0c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1d0d0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1d0e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1d0f0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1d100 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1d110 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 54  **.** {F13601} T
1d120 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
1d130 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1d140 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
1d150 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1d160 20 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69     the largest i
1d170 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20  ndex of all SQL 
1d180 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68  parameters in th
1d190 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
1d1a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d1b0 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 0a  t] S, or 0 if S.
1d1c0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
1d1d0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  ains no SQL para
1d1e0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73  meters..*/.int s
1d1f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1d200 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
1d210 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1d220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
1d230 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
1d240 6d 65 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a  meter {F13620}.*
1d250 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1d260 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1d270 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20  ter to the name 
1d280 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 53  of the n-th.** S
1d290 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  QL parameter in 
1d2a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1d2b0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70  ement]..** SQL p
1d2c0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1d2d0 20 66 6f 72 6d 20 22 3a 41 41 41 22 20 6f 72 20   form ":AAA" or 
1d2e0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
1d2f0 20 68 61 76 65 20 61 20 6e 61 6d 65 0a 2a 2a 20   have a name.** 
1d300 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
1d310 69 6e 67 20 22 3a 41 41 41 22 20 6f 72 20 22 40  ing ":AAA" or "@
1d320 41 41 41 22 20 6f 72 20 22 24 56 56 56 22 2e 20  AAA" or "$VVV". 
1d330 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
1d340 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
1d350 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
1d360 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
1d370 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
1d380 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74  name..** Paramet
1d390 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
1d3a0 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 68 61  "?" or "?NNN" ha
1d3b0 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  ve no name..**.*
1d3c0 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74  * The first host
1d3d0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
1d3e0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
1d3f0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  t 0..**.** If th
1d400 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74  e value n is out
1d410 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
1d420 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74  the n-th paramet
1d430 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
1d440 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
1d450 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72  returned.  The r
1d460 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1d470 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 74  s.** always in t
1d480 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
1d490 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
1d4a0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
1d4b0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
1d4c0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
1d4d0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
1d4e0 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
1d4f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1d500 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1d510 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1d520 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1d530 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1d540 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1d550 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1d560 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
1d570 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1d580 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1d590 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1d5a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20  .**.** {F13621} 
1d5b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
1d5c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1d5d0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
1d5e0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
1d5f0 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e       a UTF-8 ren
1d600 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61  dering of the na
1d610 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  me of the SQL pa
1d620 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20  rameter in.**   
1d630 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
1d640 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
1d650 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72  ving index N, or
1d660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c  .**          NUL
1d670 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
1d680 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77   SQL parameter w
1d690 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69  ith index N or i
1d6a0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
1d6b0 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68    parameter with
1d6c0 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61   index N is an a
1d6d0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
1d6e0 65 72 20 22 3f 22 20 6f 72 0a 2a 2a 20 20 20 20  er "?" or.**    
1d6f0 20 20 20 20 20 20 61 20 6e 75 6d 62 65 72 65 64        a numbered
1d700 20 70 61 72 61 6d 65 74 65 72 20 22 3f 4e 4e 4e   parameter "?NNN
1d710 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  "..*/.const char
1d720 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
1d730 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
1d740 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d750 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d760 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
1d770 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
1d780 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31 33 36  Given Name {F136
1d790 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  40}.**.** Return
1d7a0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
1d7b0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
1d7c0 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
1d7d0 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
1d7e0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
1d7f0 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
1d800 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
1d810 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1d820 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1d830 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1d840 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20  .  A zero.** is 
1d850 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
1d860 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
1d870 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65  r is found.  The
1d880 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
1d890 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
1d8a0 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
1d8b0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
1d8c0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
1d8d0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
1d8e0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
1d8f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d900 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
1d910 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1d920 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
1d930 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
1d940 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1d950 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1d960 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1d970 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1d980 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
1d990 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1d9a0 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54 68 65  .** {F13641} The
1d9b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1d9c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53  arameter_index(S
1d9d0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1d9e0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1d9f0 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20     the index of 
1da00 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e  SQL parameter in
1da10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1da20 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
1da30 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d    S whose name m
1da40 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38  atches the UTF-8
1da50 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20   string N, or 0 
1da60 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20  if there is.**  
1da70 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68          no match
1da80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1da90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1daa0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
1dab0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
1dac0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
1dad0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
1dae0 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
1daf0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
1db00 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a 2a 2a  ment {F13660}.**
1db10 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20  .** Contrary to 
1db20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
1db30 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
1db40 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
1db50 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20 5b  t.** reset the [
1db60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1db70 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
1db80 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64   a .** [prepared
1db90 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73   statement].  Us
1dba0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
1dbb0 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20 68  o.** reset all h
1dbc0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
1dbd0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  o NULL..**.** IN
1dbe0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1dbf0 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71  {F13661} The [sq
1dc00 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
1dc10 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61  ings(S)] interfa
1dc20 63 65 20 72 65 73 65 74 73 20 61 6c 6c 0a 2a 2a  ce resets all.**
1dc30 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 70 61            SQL pa
1dc40 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73  rameter bindings
1dc50 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74   in [prepared st
1dc60 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
1dc70 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 4e         back to N
1dc80 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
1dc90 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
1dca0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
1dcb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1dcc0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
1dcd0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
1dce0 74 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a  t Set {F13710}.*
1dcf0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
1dd00 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1dd10 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
1dd20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
1dd30 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  the .** [prepare
1dd40 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68  d statement]. Th
1dd50 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
1dd60 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74  ns 0.** if pStmt
1dd70 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65   is an SQL state
1dd80 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
1dd90 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
1dda0 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20  for .** example 
1ddb0 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2a 0a 2a  an UPDATE)..**.*
1ddc0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1ddd0 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20 54 68 65  .** {F13711} The
1dde0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1ddf0 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
1de00 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1de10 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
1de20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69         columns i
1de30 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
1de40 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68   generated by th
1de50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
1de60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1de70 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20  t] S, or 0 if S 
1de80 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74  does not generat
1de90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  e.**          a 
1dea0 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69  result set..*/.i
1deb0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
1dec0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
1ded0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1dee0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1def0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
1df00 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33   Result Set {F13
1df10 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  720}.**.** These
1df20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1df30 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
1df40 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
1df50 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
1df60 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
1df70 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  f a SELECT state
1df80 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  ment.  The sqlit
1df90 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1dfa0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
1dfb0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1dfc0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1dfd0 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67  ated UTF8 string
1dfe0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
1dff0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
1e000 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1e010 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
1e020 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 31 36 20  inated.** UTF16 
1e030 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72  string.  The fir
1e040 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1e050 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1e060 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1e070 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
1e080 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1e090 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
1e0a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1e0b0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
1e0c0 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   The left-most c
1e0d0 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62  olumn is.** numb
1e0e0 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er 0..**.** The 
1e0f0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
1e100 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
1e110 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
1e120 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  e .** [prepared 
1e130 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
1e140 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
1e150 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
1e160 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
1e170 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  next call sqlite
1e180 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
1e190 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
1e1a0 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e  n_name16().** on
1e1b0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
1e1c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ..**.** If sqlit
1e1d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
1e1e0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
1e1f0 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
1e200 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
1e210 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
1e220 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
1e230 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
1e240 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
1e250 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
1e260 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
1e270 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
1e280 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
1e290 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
1e2a0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
1e2b0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
1e2c0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
1e2d0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
1e2e0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
1e2f0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
1e300 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
1e310 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
1e320 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
1e330 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
1e340 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
1e350 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20  the next..**.** 
1e360 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1e370 2a 20 7b 46 31 33 37 32 31 7d 20 41 20 73 75 63  * {F13721} A suc
1e380 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
1e390 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
1e3a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
1e3b0 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
1e3c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1e3d0 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  ns the name.**  
1e3e0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e          of the N
1e3f0 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65  th column (where
1e400 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d   0 is the left-m
1e410 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
1e420 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1e430 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
1e440 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e450 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20  t] S as a.**    
1e460 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
1e470 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1e480 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  ng..**.** {F1372
1e490 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
1e4a0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
1e4b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1e4c0 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a  n_name16(S,N)].*
1e4d0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
1e4e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1e4f0 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   name.**        
1e500 20 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    of the Nth col
1e510 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 20  umn (where 0 is 
1e520 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  the left-most co
1e530 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a  lumn) for the.**
1e540 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
1e550 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
1e560 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
1e570 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
1e580 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1e590 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1e5a0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1e5b0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46   order..**.** {F
1e5c0 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  13724} The [sqli
1e5d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1e5e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e5f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d  column_name16()]
1e600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
1e610 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61  erfaces return a
1e620 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1e630 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65   they are unable
1e640 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1e650 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
1e660 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1e670 68 65 72 65 20 6e 6f 72 6d 61 6c 20 72 65 74 75  here normal retu
1e680 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a  rn strings..**.*
1e690 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74 68  * {F13725} If th
1e6a0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1e6b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1e6c0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _name(S,N)] or.*
1e6d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1e6e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1e6f0 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f  6(S,N)] is out o
1e700 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68  f range, then th
1e710 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
1e720 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 73  terfaces returns
1e730 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1e740 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 36 7d  .** .** {F13726}
1e750 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1e760 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1e770 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
1e780 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  N)] and.**      
1e790 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
1e7a0 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
1e7b0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
1e7c0 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20   the next.**    
1e7d0 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69        call to ei
1e7e0 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74  ther routine wit
1e7f0 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64  h the same S and
1e800 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a   N parameters.**
1e810 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
1e820 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  il [sqlite3_fina
1e830 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
1e840 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  ed..**.** {F1372
1e850 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74  7} When a result
1e860 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45   column of a [SE
1e870 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
1e880 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20  contains.**     
1e890 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73       an AS claus
1e8a0 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  e, the name of t
1e8b0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  hat column is th
1e8c0 65 20 69 6e 64 65 6e 74 69 66 69 65 72 0a 2a 2a  e indentifier.**
1e8d0 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
1e8e0 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53   right of the AS
1e8f0 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e   keyword..*/.con
1e900 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1e910 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
1e920 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1e930 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
1e940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1e950 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1e960 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
1e970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
1e980 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
1e990 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
1e9a0 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13740}.**.** Th
1e9b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
1e9c0 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
1e9d0 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63  determine what c
1e9e0 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a  olumn of what.**
1e9f0 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20   table in which 
1ea00 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c  database a resul
1ea10 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
1ea20 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72  atement comes fr
1ea30 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  om..** The name 
1ea40 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1ea50 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
1ea60 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
1ea70 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
1ea80 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20  a UTF8 or UTF16 
1ea90 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61  string.  The _da
1eaa0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
1eab0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
1eac0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
1ead0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
1eae0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
1eaf0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
1eb00 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
1eb10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
1eb20 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
1eb30 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
1eb40 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
1eb50 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 70 72 65 70  til.** the [prep
1eb60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1eb70 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  is destroyed usi
1eb80 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1eb90 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
1eba0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
1ebb0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
1ebc0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
1ebd0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
1ebe0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  coding..**.** Th
1ebf0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
1ec00 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
1ec10 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
1ec20 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
1ec30 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
1ec40 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
1ec50 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1ec60 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77  nt to the follow
1ec70 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b  ing calls is a [
1ec80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ec90 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75  nt]..** These fu
1eca0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
1ecb0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
1ecc0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1ecd0 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20  returned by .** 
1ece0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
1ecf0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1ed00 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
1ed10 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  gument..**.** If
1ed20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1ed30 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
1ed40 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
1ed50 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72  expression.** or
1ed60 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
1ed70 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
1ed80 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
1ed90 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
1eda0 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  .** return NULL.
1edb0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20    These routine 
1edc0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
1edd0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
1ede0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
1edf0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
1ee00 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
1ee10 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e  return the .** n
1ee20 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
1ee30 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
1ee40 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  ble and column t
1ee50 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
1ee60 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  .** column was e
1ee70 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
1ee80 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c  *.** As with all
1ee90 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
1eea0 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69  Is, those postfi
1eeb0 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65  xed with "16" re
1eec0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
1eed0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20  ncoded strings, 
1eee0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
1eef0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
1ef00 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
1ef10 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
1ef20 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
1ef30 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
1ef40 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
1ef50 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42   .** SQLITE_ENAB
1ef60 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
1ef70 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20  TA preprocessor 
1ef80 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
1ef90 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a  **.** {U13751}.*
1efa0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
1efb0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
1efc0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
1efd0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
1efe0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
1eff0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f000 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
1f010 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1f020 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1f030 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
1f040 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1f050 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34  TS:.**.** {F1374
1f060 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1f070 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1f080 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
1f090 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
1f0a0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
1f0b0 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
1f0c0 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
1f0d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
1f0e0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1f0f0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1f100 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1f110 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f120 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1f130 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1f140 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1f150 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f160 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1f170 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1f180 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1f190 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f1a0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1f1b0 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1f1c0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1f1d0 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 32 7d      .** {F13742}
1f1e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1f1f0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1f200 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
1f210 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
1f220 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
1f230 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
1f240 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
1f250 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1f260 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
1f270 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
1f280 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a  om which the .**
1f290 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
1f2a0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b  sult column of [
1f2b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f2c0 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20  nt] S .**       
1f2d0 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c     is extracted,
1f2e0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
1f2f0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1f300 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  f S is a.**     
1f310 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70       general exp
1f320 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e  ression or if un
1f330 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1f340 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
1f350 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65      to store the
1f360 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20   name..**       
1f370 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 33 7d 20     .** {F13743} 
1f380 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
1f390 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53  umn_table_name(S
1f3a0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1f3b0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
1f3c0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
1f3d0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1f3e0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
1f3f0 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68  table from which
1f400 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1f410 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
1f420 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
1f430 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
1f440 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
1f450 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
1f460 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20   if the the Nth 
1f470 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
1f480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
1f490 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
1f4a0 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
1f4b0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
1f4c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
1f4d0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
1f4e0 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
1f4f0 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c  F13744} The [sql
1f500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
1f510 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  e_name16(S,N)] i
1f520 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1f530 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
1f540 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
1f550 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1f560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1f570 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
1f580 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66  e of the table f
1f590 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1f5a0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1f5b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1f5c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f5d0 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1f5e0 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1f5f0 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1f600 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f610 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1f620 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1f630 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1f640 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f650 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1f660 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1f670 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1f680 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 35 7d      .** {F13745}
1f690 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1f6a0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
1f6b0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
1f6c0 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
1f6d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1f6e0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1f6f0 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
1f700 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66  e table column f
1f710 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1f720 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1f730 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1f740 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f750 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1f760 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1f770 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1f780 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f790 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1f7a0 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1f7b0 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1f7c0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f7d0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1f7e0 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1f7f0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1f800 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 36 7d      .** {F13746}
1f810 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1f820 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
1f830 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
1f840 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
1f850 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
1f860 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
1f870 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
1f880 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1f890 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
1f8a0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1f8b0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
1f8c0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
1f8d0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1f8e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f8f0 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
1f900 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
1f910 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
1f920 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  e the Nth column
1f930 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1f940 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1f950 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1f960 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1f970 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1f980 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1f990 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1f9a0 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 38       .** {F13748
1f9b0 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
1f9c0 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ues from.**     
1f9d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
1f9e0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1f9f0 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61  me|column metada
1fa00 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
1fa10 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76  *          are v
1fa20 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  alid.**         
1fa30 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d   for the lifetim
1fa40 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  e of the [prepar
1fa50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
1fa60 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
1fa70 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  il the encoding 
1fa80 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e  is changed by an
1fa90 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a  other metadata.*
1faa0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
1fab0 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68  face call for th
1fac0 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 64 20  e same prepared 
1fad0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
1fae0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  lumn..**.** LIMI
1faf0 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
1fb00 55 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f  U13751} If two o
1fb10 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
1fb20 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
1fb30 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1fb40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1fb50 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e  base_name|column
1fb60 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
1fb70 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  aces].**        
1fb80 20 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70    the same [prep
1fb90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1fba0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
1fbb0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74  n.**          at
1fbc0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1fbd0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1fbe0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
1fbf0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1fc00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
1fc10 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
1fc20 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1fc30 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1fc40 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
1fc50 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
1fc60 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1fc70 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1fc80 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
1fc90 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1fca0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1fcb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1fcc0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
1fcd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1fce0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
1fcf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
1fd00 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
1fd10 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1fd20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1fd30 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
1fd40 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1fd50 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
1fd60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
1fd70 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
1fd80 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
1fd90 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F13760}.**.** 
1fda0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1fdb0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
1fdc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a  ed statement]. .
1fdd0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
1fde0 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54  ment is a SELECT
1fdf0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
1fe00 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
1fe10 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65   the .** returne
1fe20 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
1fe30 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20 61  that SELECT is a
1fe40 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
1fe50 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
1fe60 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
1fe70 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
1fe80 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
1fe90 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
1fea0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20  s returned.  If 
1feb0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1fec0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
1fed0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
1fee0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
1fef0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
1ff00 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
1ff10 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
1ff20 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
1ff30 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
1ff40 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46 6f  d.  {END} .** Fo
1ff50 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68  r example, in th
1ff60 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1ff70 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
1ff80 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
1ff90 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20  ANT);.**.** And 
1ffa0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
1ffb0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64  atement compiled
1ffc0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
1ffd0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
1ffe0 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68  1;.**.** Then th
1fff0 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
20000 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
20010 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
20020 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72   the second.** r
20030 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
20040 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
20050 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
20060 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
20070 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a  umn.** (i==0)..*
20080 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
20090 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
200a0 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75  e typing.  So ju
200b0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
200c0 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
200d0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
200e0 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
200f0 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
20100 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
20110 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
20120 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
20130 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
20140 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
20150 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
20160 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
20170 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
20180 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73  .  Type.** is as
20190 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
201a0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
201b0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
201c0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
201d0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
201e0 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  alues..**.** INV
201f0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
20200 46 31 33 37 36 31 7d 20 20 41 20 73 75 63 63 65  F13761}  A succe
20210 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
20220 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
20230 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a 2a 2a 20  cltype(S,N)].** 
20240 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
20250 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
20260 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
20270 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
20280 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
20290 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79   declared dataty
202a0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  pe of the table 
202b0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65  column that appe
202c0 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ars.**          
202d0 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   as the Nth colu
202e0 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f  mn (numbered fro
202f0 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75  m 0) of the resu
20300 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a  lt set to the.**
20310 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
20320 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20330 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 32  S..**.** {F13762
20340 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  }  A successful 
20350 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
20360 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
20370 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20  16(S,N)].**     
20380 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
20390 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
203a0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
203b0 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a  te order string.
203c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e  **           con
203d0 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c  taining the decl
203e0 61 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66  ared datatype of
203f0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
20400 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a  n that appears.*
20410 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74  *           as t
20420 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e  he Nth column (n
20430 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20  umbered from 0) 
20440 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
20450 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  t to the.**     
20460 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
20470 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
20480 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20 49 66  .** {F13763}  If
20490 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
204a0 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65  0 or N is greate
204b0 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  r than or equal 
204c0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  to.**           
204d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
204e0 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65 70 61 72  lumns in [prepar
204f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
20500 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20  **           or 
20510 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
20520 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70  n of S is an exp
20530 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
20540 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20  ery rather.**   
20550 20 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74          than a t
20560 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72 20 69  able column or i
20570 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
20580 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a  ation failure.**
20590 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
205a0 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e  s during encodin
205b0 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74  g conversions, t
205c0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
205d0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
205e0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
205f0 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  pe(S,N)] or.**  
20600 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
20610 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
20620 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e  e16(S,N)] return
20630 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   NULL..*/.const 
20640 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
20650 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
20660 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
20670 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
20680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
20690 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
206a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20  stmt*,int);../* 
206b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
206c0 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
206d0 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 32 30 30  tatement {F13200
206e0 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e  }.**.** After an
206f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20700 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
20710 72 65 70 61 72 65 64 20 77 69 74 68 20 61 20 63  repared with a c
20720 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72  all.** to either
20730 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20740 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
20750 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
20760 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66  ()] or to one of
20770 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69  .** the legacy i
20780 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
20790 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
207a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
207b0 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  e16()],.** then 
207c0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75  this function mu
207d0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
207e0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
207f0 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a  o evaluate the .
20800 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  ** statement..**
20810 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
20820 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
20830 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  of this sqlite3_
20840 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
20850 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
20860 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
20870 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
20880 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
20890 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
208a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
208b0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
208c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
208d0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
208e0 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
208f0 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
20900 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
20910 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20920 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
20930 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
20940 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
20950 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
20960 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
20970 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
20980 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
20990 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
209a0 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
209b0 2a 20 49 6e 20 74 68 65 20 6c 61 67 61 63 79 20  * In the lagacy 
209c0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
209d0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
209e0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
209f0 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53  TE_BUSY], .** [S
20a00 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
20a10 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
20a20 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
20a30 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
20a40 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  * With the "v2" 
20a50 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
20a60 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c  f the other [SQL
20a70 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
20a80 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  code].** or [SQL
20a90 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
20aa0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
20ab0 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20   code] might be 
20ac0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77  returned as.** w
20ad0 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ell..**.** [SQLI
20ae0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
20af0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
20b00 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
20b10 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
20b20 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
20b30 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
20b40 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20  do its job.  If 
20b50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
20b60 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20   a COMMIT.** or 
20b70 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
20b80 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
20b90 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
20ba0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
20bb0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
20bc0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
20bd0 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49  t is not a COMMI
20be0 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  T and occurs wit
20bf0 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69  hin a.** explici
20c00 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
20c10 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
20c20 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
20c30 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
20c40 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
20c50 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
20c60 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
20c70 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
20c80 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
20c90 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
20ca0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
20cb0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
20cc0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
20cd0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
20ce0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
20cf0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
20d00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
20d10 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
20d20 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
20d30 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
20d40 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
20d50 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
20d60 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
20d70 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
20d80 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20   data, then .** 
20d90 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20  [SQLITE_ROW] is 
20da0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
20db0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
20dc0 64 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a  data is ready.**
20dd0 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
20de0 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54  by the caller. T
20df0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
20e00 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a   accessed using.
20e10 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
20e20 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c  column_int | col
20e30 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
20e40 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
20e50 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
20e60 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
20e70 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
20e80 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a  w of data..** .*
20e90 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
20ea0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
20eb0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
20ec0 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
20ed0 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
20ee0 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
20ef0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
20f00 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
20f10 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
20f20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
20f30 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
20f40 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
20f50 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
20f60 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  ()]..** With the
20f70 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
20f80 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
20f90 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65  ic error code (e
20fa0 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49  xample:.** [SQLI
20fb0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
20fc0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
20fd0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
20fe0 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
20ff0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
21000 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
21010 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21020 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
21030 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
21040 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
21050 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
21060 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
21070 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
21080 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
21090 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
210a0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
210b0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
210c0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
210d0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
210e0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
210f0 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
21100 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
21110 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21120 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
21130 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
21140 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
21150 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
21160 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20  ne that had .** 
21170 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
21180 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
21190 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
211a0 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
211b0 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
211c0 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
211d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
211e0 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
211f0 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
21200 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
21210 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
21220 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   time..**.** <b>
21230 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
21240 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e  Alert:</b>.** In
21250 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
21260 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73  rface, .** the s
21270 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41 50  qlite3_step() AP
21280 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
21290 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
212a0 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54   code,.** [SQLIT
212b0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
212c0 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74  ing any error ot
212d0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
212e0 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53  _BUSY].** and [S
212f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
21300 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73  You must call [s
21310 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21320 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
21330 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
21340 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
21350 6f 66 20 74 68 65 20 73 70 65 63 69 66 69 63 0a  of the specific.
21360 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
21370 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
21380 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
21390 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
213a0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
213b0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
213c0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
213d0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
213e0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
213f0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
21400 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
21410 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
21420 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
21430 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21440 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
21450 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
21460 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
21470 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
21480 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
21490 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
214a0 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68  re16()], then th
214b0 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69  e .** more speci
214c0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
214d0 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
214e0 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
214f0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
21500 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
21510 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
21520 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
21530 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
21540 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20 49  *.** {F13202}  I
21550 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
21560 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64  ement] S is read
21570 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20 20 20 20  y to be.**      
21580 20 20 20 20 20 72 75 6e 2c 20 74 68 65 6e 20 5b       run, then [
21590 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
215a0 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70   advances that p
215b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
215c0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 75  t.**           u
215d0 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c 65 74 69  ntil to completi
215e0 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69  on or until it i
215f0 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
21600 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20 20 20 20  n another.**    
21610 20 20 20 20 20 20 20 72 6f 77 20 6f 66 20 74 68         row of th
21620 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 72 20  e result set or 
21630 61 6e 20 69 6e 74 65 72 72 75 70 74 20 6f 72 20  an interrupt or 
21640 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f  run-time error o
21650 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ccurs..**.** {F1
21660 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61  5304}  When a ca
21670 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
21680 74 65 70 28 53 29 5d 20 63 61 75 73 65 73 20 74  tep(S)] causes t
21690 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
216a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
216b0 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75 6e 20 74  ment] S to run t
216c0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a 2a 2a  o completion,.**
216d0 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66             the f
216e0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
216f0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a  [SQLITE_DONE]..*
21700 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20 57  *.** {F15306}  W
21710 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  hen a call to [s
21720 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
21730 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 69 74  stops because it
21740 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 20 20 20   is ready.**    
21750 20 20 20 20 20 20 20 74 6f 20 72 65 74 75 72 6e         to return
21760 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
21770 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20  the result set, 
21780 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  it returns.**   
21790 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
217a0 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ROW]..**.** {F15
217b0 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20  308}  If a call 
217c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
217d0 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20  (S)] encounters 
217e0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
217f0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
21800 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72  pt|interrupt] or
21810 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
21820 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  r,.**           
21830 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  it returns an ap
21840 70 72 6f 70 72 61 69 74 65 20 65 72 72 6f 72 20  propraite error 
21850 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74  code that is not
21860 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20   one of.**      
21870 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
21880 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
21890 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
218a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 30 7d  ..**.** {F15310}
218b0 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33    If an [sqlite3
218c0 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72  _interrupt|inter
218d0 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d 74 69 6d  rupt] or run-tim
218e0 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20  e error.**      
218f0 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69       occurs duri
21900 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
21910 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a  lite3_step(S)].*
21920 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  *           for 
21930 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21940 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64  ement] S created
21950 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
21960 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72      legacy inter
21970 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
21980 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20  repare()] or.** 
21990 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
219a0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
219b0 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  then the functio
219c0 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  n returns either
219d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
219e0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53  QLITE_ERROR], [S
219f0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20  QLITE_BUSY], or 
21a00 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
21a10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
21a20 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
21a30 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
21a40 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
21a50 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
21a60 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37 30 7d  ult set {F13770}
21a70 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
21a80 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75  e number of valu
21a90 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  es in the curren
21aa0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
21ab0 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49  ult set..**.** I
21ac0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
21ad0 20 7b 46 31 33 37 37 31 7d 20 20 41 66 74 65 72   {F13771}  After
21ae0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
21af0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61  te3_step(S)] tha
21b00 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  t returns.**    
21b10 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52         [SQLITE_R
21b20 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  OW], the [sqlite
21b30 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d  3_data_count(S)]
21b40 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20   routine.**     
21b50 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72        will retur
21b60 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  n the same value
21b70 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   as the.**      
21b80 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
21b90 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66  lumn_count(S)] f
21ba0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  unction..**.** {
21bb0 46 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b  F13772}  After [
21bc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
21bd0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e   has returned an
21be0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
21bf0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
21c00 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
21c10 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
21c20 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65  step(S)] has bee
21c30 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  n .**           
21c40 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 70  called on the [p
21c50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21c60 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  t] for.**       
21c70 20 20 20 20 74 68 65 20 66 69 72 73 74 20 74 69      the first ti
21c80 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73 20  me since it was 
21c90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21ca0 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a 20 20 20  |prepared].**   
21cb0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
21cc0 74 65 33 5f 72 65 73 65 74 7c 72 65 73 65 74 5d  te3_reset|reset]
21cd0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  , the [sqlite3_d
21ce0 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 0a 2a 2a  ata_count(S)].**
21cf0 20 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69             routi
21d00 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  ne returns zero.
21d10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
21d20 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
21d30 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
21d40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21d50 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
21d60 74 61 74 79 70 65 73 20 7b 46 31 30 32 36 35 7d  tatypes {F10265}
21d70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
21d80 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
21d90 7b 46 31 30 32 36 36 7d 45 76 65 72 79 20 76 61  {F10266}Every va
21da0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
21db0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
21dc0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
21dd0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
21de0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
21df0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
21e00 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
21e10 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
21e20 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
21e30 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
21e40 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
21e50 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
21e60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
21e70 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
21e80 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
21e90 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
21ea0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
21eb0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
21ec0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
21ed0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
21ee0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
21ef0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
21f00 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
21f10 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
21f20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
21f30 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
21f40 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
21f50 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
21f60 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f   SQLITE3_TEXT no
21f70 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
21f80 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
21f90 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
21fa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
21fb0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
21fc0 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
21fd0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
21fe0 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
21ff0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
22000 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
22010 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
22020 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
22030 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
22040 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
22050 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
22060 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20  PI3REF: Results 
22070 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
22080 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 0a  ery {F13800}.**.
22090 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
220a0 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
220b0 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e  lt set query" in
220c0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
220d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
220e0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
220f0 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67   about.** a sing
22100 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
22110 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20   current result 
22120 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
22130 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73   In every.** cas
22140 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
22150 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
22160 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 70 72  r to the .** [pr
22170 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22180 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 0a  ] that is being.
22190 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ** evaluated (th
221a0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
221b0 5d 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ] that was retur
221c0 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
221d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
221e0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
221f0 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e 64 0a  s variants) and.
22200 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  ** the second ar
22210 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
22220 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
22230 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
22240 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75  rmation .** shou
22250 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
22260 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   The left-most c
22270 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
22280 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 61  ult set.** has a
22290 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a  n index of 0..**
222a0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
222b0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
222c0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
222d0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
222e0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65  or if the.** the
222f0 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
22300 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
22310 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
22320 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73  efined. .** Thes
22330 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
22340 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
22350 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
22360 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
22370 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
22380 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
22390 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
223a0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
223b0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
223c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
223d0 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
223e0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
223f0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
22400 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
22410 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
22420 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
22430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
22440 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
22450 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
22460 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
22470 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
22480 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
22490 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
224a0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
224b0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
224c0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
224d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
224e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
224f0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
22500 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
22510 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
22520 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
22530 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
22540 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
22550 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
22560 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  fined.  .**.** T
22570 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
22580 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
22590 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
225a0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
225b0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
225c0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
225d0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
225e0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
225f0 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76    The returned v
22600 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
22610 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
22620 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
22630 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
22640 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
22650 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
22660 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
22670 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
22680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
22690 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
226a0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
226b0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
226c0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
226d0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
226e0 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
226f0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
22700 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
22710 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
22720 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
22730 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
22740 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
22750 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
22760 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
22770 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
22780 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
22790 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
227a0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  version..**.** I
227b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
227c0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
227d0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
227e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
227f0 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69  ytes() .** routi
22800 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
22810 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
22820 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
22830 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65  tring..** If the
22840 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
22850 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
22860 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22870 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
22880 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
22890 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
228a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
228b0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
228c0 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
228d0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
228e0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
228f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
22900 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
22910 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
22920 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
22930 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
22940 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
22950 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
22960 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
22970 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  ring..** The val
22980 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  ue returned does
22990 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
229a0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
229b0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
229c0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46  f the string.  F
229d0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
229e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
229f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
22a00 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
22a10 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
22a20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
22a30 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69  ters..**.** Stri
22a40 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
22a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22a60 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
22a70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
22a80 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
22a90 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
22aa0 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
22ab0 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  ated.  The retur
22ac0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
22ad0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22ae0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
22af0 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20  -length blob is 
22b00 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  an arbitrary.** 
22b10 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c  pointer, possibl
22b20 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  y even a NULL po
22b30 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
22b40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22b50 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
22b60 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
22b70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22b80 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
22b90 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
22ba0 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  in UTF-16 in nat
22bb0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
22bc0 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
22bd0 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74    .** The zero t
22be0 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74  erminator is not
22bf0 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69   included in thi
22c00 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  s count..**.** T
22c10 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
22c20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
22c30 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
22c40 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
22c50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
22c60 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
22c70 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
22c80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22c90 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
22ca0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
22cb0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
22cc0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
22cd0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
22ce0 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
22cf0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
22d00 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
22d10 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
22d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
22d30 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
22d40 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
22d50 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
22d60 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
22d70 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
22d80 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
22d90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
22da0 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
22db0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
22dc0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
22dd0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
22de0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
22df0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
22e00 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
22e10 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
22e20 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a  opriate.  For.**
22e30 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
22e40 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
22e50 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
22e60 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
22e70 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
22e80 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
22e90 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
22ea0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
22eb0 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  do the conversio
22ec0 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  n.** automatical
22ed0 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ly.  The followi
22ee0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
22ef0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
22f00 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70   that.** are app
22f10 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
22f20 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
22f30 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
22f40 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
22f50 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
22f60 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
22f70 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
22f80 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
22f90 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
22fa0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
22fb0 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
22fc0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
22fd0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
22fe0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
22ff0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
23000 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
23010 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
23020 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
23030 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
23040 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
23050 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
23060 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
23070 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
23080 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
23090 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
230a0 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
230b0 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
230c0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
230d0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
230e0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
230f0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
23100 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
23110 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
23120 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
23130 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e  as for INTEGER->
23140 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
23150 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
23160 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
23170 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
23180 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
23190 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
231a0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
231b0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
231c0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
231d0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
231e0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
231f0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
23200 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
23210 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
23220 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
23230 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
23240 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
23250 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
23260 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
23270 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
23280 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
23290 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
232a0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
232b0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
232c0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
232d0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
232e0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
232f0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
23300 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
23310 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
23320 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
23330 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
23340 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
23350 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
23360 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
23370 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
23380 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
23390 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
233a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
233b0 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
233c0 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
233d0 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
233e0 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
233f0 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
23400 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
23410 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
23420 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
23430 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75  as its.** on equ
23440 61 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  avalent internal
23450 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
23460 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
23470 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
23480 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
23490 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
234a0 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
234b0 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
234c0 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
234d0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
234e0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
234f0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
23500 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
23510 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
23520 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
23530 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
23540 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23550 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
23560 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23570 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
23580 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a  invalidated. .**
23590 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
235a0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
235b0 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
235c0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
235d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
235e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
235f0 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
23600 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
23610 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
23620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23630 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ) .**          o
23640 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
23650 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
23660 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
23670 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
23680 20 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74            need t
23690 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
236a0 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c  e string.</p></l
236b0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e  i>.**.** <li><p>
236c0 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
236d0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
236e0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
236f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
23700 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
23710 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23720 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
23730 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
23740 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
23750 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  d.**          to
23760 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69   UTF-16.</p></li
23770 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  >.**.** <li><p> 
23780 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
23790 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
237a0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
237b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
237c0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71  r.**          sq
237d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
237e0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
237f0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
23800 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
23810 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46            to UTF
23820 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20  -8.</p></li>.** 
23830 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76  </ul>.**.** Conv
23840 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
23850 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
23860 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
23870 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
23880 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
23890 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
238a0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
238b0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
238c0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
238d0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
238e0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
238f0 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
23900 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
23910 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
23920 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
23930 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
23940 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
23950 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
23960 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  me it is.** not 
23970 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
23980 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
23990 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
239a0 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a  nvalidated.  .**
239b0 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
239c0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
239d0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
239e0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
239f0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
23a00 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
23a10 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
23a20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73    <ul>.**  <li>s
23a30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23a40 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
23a50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23a60 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
23a70 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
23a80 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
23a90 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
23aa0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
23ab0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
23ac0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23ad0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
23ae0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23af0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
23b00 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
23b10 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
23b20 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
23b30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23b40 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
23b50 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72  mn_blob(),.** or
23b60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23b70 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
23b80 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
23b90 6c 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  lt into the desi
23ba0 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74  red.** format, t
23bb0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
23bc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23bd0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
23be0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
23bf0 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a  .** find the siz
23c00 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
23c10 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
23c20 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  l to sqlite3_col
23c30 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
23c40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23c50 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
23c60 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
23c70 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20  umn_bytes16().  
23c80 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69  And do not.** mi
23c90 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
23ca0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23cb0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
23cc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23cd0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  bytes()..**.** T
23ce0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
23cf0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
23d00 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
23d10 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
23d20 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
23d30 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
23d40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
23d50 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
23d60 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
23d70 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
23d80 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d  s called.  The m
23d90 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
23da0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
23db0 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73  .** and blobs is
23dc0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
23dd0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
23de0 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
23df0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
23e00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
23e10 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
23e20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23e30 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a  ()], etc. into .
23e40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
23e50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  ()]..**.** If a 
23e60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
23e70 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
23e80 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
23e90 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
23ea0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
23eb0 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
23ec0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
23ed0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
23ee0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
23ef0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
23f00 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
23f10 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
23f20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
23f30 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
23f40 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
23f50 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
23f60 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
23f70 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
23f80 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
23f90 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54 68 65 20  ** {F13803} The 
23fa0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23fb0 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72  blob(S,N)] inter
23fc0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
23fd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
23fe0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
23ff0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
24000 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
24010 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
24020 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24030 74 5d 20 53 20 69 6e 74 6f 20 61 20 62 6c 6f 62  t] S into a blob
24040 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
24050 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
24060 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
24070 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a  onverted value..
24080 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36 7d 20 54  **.** {F13806} T
24090 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
240a0 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69  mn_bytes(S,N)] i
240b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
240c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
240d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
240e0 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20   in the blob or 
240f0 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
24100 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
24110 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
24120 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
24130 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
24140 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
24150 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
24160 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
24170 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
24180 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20  b(S,N)] or.**   
24190 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
241a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29  column_text(S,N)
241b0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 39  ]..**.** {F13809
241c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
241d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c  olumn_bytes16(S,
241e0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
241f0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
24200 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
24210 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
24220 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
24230 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
24240 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
24250 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
24260 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
24270 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
24280 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
24290 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
242a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
242b0 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  (S,N)]..**.** {F
242c0 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  13812} The [sqli
242d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
242e0 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
242f0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
24300 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
24310 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
24320 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
24330 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
24340 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
24350 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24360 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e  S into a floatin
24370 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e  g point value an
24380 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
24390 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
243a0 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  that value..**.*
243b0 2a 20 7b 46 31 33 38 31 35 7d 20 54 68 65 20 5b  * {F13815} The [
243c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
243d0 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  nt(S,N)] interfa
243e0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
243f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
24400 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
24410 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
24420 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
24430 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
24440 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24450 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
24460 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
24470 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
24480 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65  returns the lowe
24490 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61  r 32 bits of tha
244a0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
244b0 20 7b 46 31 33 38 31 38 7d 20 54 68 65 20 5b 73   {F13818} The [s
244c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
244d0 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  t64(S,N)] interf
244e0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
244f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
24500 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
24510 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
24520 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
24530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
24540 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24550 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  ] S into a 64-bi
24560 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
24570 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
24580 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
24590 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
245a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d 20  .**.** {F13821} 
245b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
245c0 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69  umn_text(S,N)] i
245d0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
245e0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
245f0 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
24600 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
24610 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
24620 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
24630 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
24640 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
24650 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24660 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20  UTF-8 .**       
24670 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
24680 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
24690 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
246a0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34 7d 20 54  **.** {F13824} T
246b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
246c0 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20  mn_text16(S,N)] 
246d0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
246e0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
246f0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
24700 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
24710 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
24720 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
24730 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
24740 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
24750 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
24760 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20   2-byte.**      
24770 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d      aligned UTF-
24780 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
24790 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
247a0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
247b0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
247c0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
247d0 0a 2a 2a 20 7b 46 31 33 38 32 37 7d 20 54 68 65  .** {F13827} The
247e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
247f0 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _type(S,N)] inte
24800 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
24810 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66            one of
24820 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20   [SQLITE_NULL], 
24830 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
24840 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  , [SQLITE_FLOAT]
24850 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
24860 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20  QLITE_TEXT], or 
24870 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73  [SQLITE_BLOB] as
24880 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
24890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
248a0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
248b0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
248c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
248d0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
248e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
248f0 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
24900 46 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c  F13830} The [sql
24910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
24920 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
24930 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  e returns a.**  
24940 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
24950 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  to an [unprotect
24960 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
24970 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65  ] object for the
24980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
24990 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
249a0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
249b0 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
249c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
249d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
249e0 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ] S..*/.const vo
249f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
24a00 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
24a10 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24a20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
24a30 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
24a40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24a50 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
24a60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
24a70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24a80 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
24a90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24aa0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
24ab0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24ac0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
24ad0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
24ae0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24af0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
24b00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
24b10 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
24b20 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
24b30 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
24b40 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
24b50 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
24b60 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24b70 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24b80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24b90 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
24ba0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
24bb0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
24bc0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
24bd0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24be0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
24bf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
24c00 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
24c10 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
24c20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
24c30 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
24c40 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
24c50 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a 2a  ct {F13300}.**.*
24c60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69  * The sqlite3_fi
24c70 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
24c80 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
24c90 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70 72 65  elete a .** [pre
24ca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24cb0 2e 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65  . If the stateme
24cc0 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74  nt was.** execut
24cd0 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  ed successfully,
24ce0 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64   or not executed
24cf0 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51   at all, then SQ
24d00 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72  LITE_OK is retur
24d10 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75  ned..** If execu
24d20 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
24d30 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65  ement failed the
24d40 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20  n an .** [error 
24d50 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
24d60 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a  ed error code].*
24d70 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a  * is returned. .
24d80 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
24d90 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
24da0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
24db0 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ring the executi
24dc0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72  on of the.** [pr
24dd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24de0 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75  ].  If the virtu
24df0 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e  al machine has n
24e00 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  ot .** completed
24e10 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20   execution when 
24e20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
24e30 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20  called, that is 
24e40 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  like.** encounte
24e50 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72  ring an error or
24e60 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20   an interrupt.  
24e70 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  (See [sqlite3_in
24e80 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a  terrupt()].) .**
24e90 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61   Incomplete upda
24ea0 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65  tes may be rolle
24eb0 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73  d back and trans
24ec0 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65  actions cancelle
24ed0 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e  d,  .** dependin
24ee0 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73  g on the circums
24ef0 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20  tances, and the 
24f00 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
24f10 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
24f20 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
24f30 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
24f40 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30  TS:.**.** {F1130
24f50 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
24f60 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74  finalize(S)] int
24f70 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 73 20  erface destroys 
24f80 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24f90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24fa0 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61  ent] S and relea
24fb0 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ses all.**      
24fc0 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66      memory and f
24fd0 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68 65  ile resources he
24fe0 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63  ld by that objec
24ff0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 34  t..**.** {F11304
25000 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
25010 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
25020 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
25030 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
25040 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
25050 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
25060 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20  ed an error,.** 
25070 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
25080 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
25090 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74  S)] returns that
250a0 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a   same error..*/.
250b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
250c0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
250d0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
250e0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
250f0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
25100 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46  tement Object {F
25110 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13330}.**.** The
25120 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
25130 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
25140 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a  led to reset a .
25150 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
25160 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a  tement] object..
25170 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ** back to its i
25180 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
25190 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
251a0 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51  cuted..** Any SQ
251b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
251c0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
251d0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
251e0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
251f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25200 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
25210 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
25220 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
25230 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
25240 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
25250 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
25260 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
25270 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71  {F11332} The [sq
25280 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
25290 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
252a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
252b0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20  tatement] S.**  
252c0 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20          back to 
252d0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
252e0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
252f0 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49 66 20  .** {F11334} If 
25300 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
25310 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
25320 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 0a 2a  _step(S)] for .*
25330 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
25340 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25350 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
25360 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
25370 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20  TE_DONE],.**    
25380 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c        or if [sql
25390 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
253a0 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
253b0 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
253c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
253d0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
253e0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
253f0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
25400 7b 46 31 31 33 33 36 7d 20 49 66 20 74 68 65 20  {F11336} If the 
25410 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
25420 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
25430 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20  p(S)] for.**    
25440 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
25450 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
25460 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
25470 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
25480 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74    [sqlite3_reset
25490 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
254a0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
254b0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
254c0 7b 46 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71  {F11338} The [sq
254d0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
254e0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
254f0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
25500 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  lues.**         
25510 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
25520 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
25530 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61 72 65  ngs] on [prepare
25540 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
25550 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
25560 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
25570 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
25580 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
25590 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
255a0 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31  QL Functions {F1
255b0 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  6100}.** KEYWORD
255c0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
255d0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 20  ation routines} 
255e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f  .**.** These two
255f0 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
25600 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
25610 73 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e 20 63  s.** "function c
25620 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
25630 22 29 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ") are used to a
25640 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
25650 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a   or aggregates.*
25660 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  * or to redefine
25670 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
25680 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
25690 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
256a0 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64  gates.  The.** d
256b0 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62  ifference only b
256c0 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69  etween the two i
256d0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
256e0 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  d parameter, the
256f0 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
25700 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f  (scalar) functio
25710 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
25720 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  is encoded in UT
25730 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
25740 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25750 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20  on() and UTF-16 
25760 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
25770 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e  te_function16().
25780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
25790 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
257a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
257b0 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
257c0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
257d0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
257e0 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c  ded.  If a singl
257f0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
25800 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
25810 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25820 74 69 6f 6e 5d 20 69 6e 74 65 72 6e 61 6c 6c 79  tion] internally
25830 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75  , then SQL.** fu
25840 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
25850 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c  added individual
25860 6c 79 20 74 6f 20 65 61 63 68 20 5b 64 61 74 61  ly to each [data
25870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25880 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
25890 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
258a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
258b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
258c0 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72  be created.** or
258d0 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   redefined..** T
258e0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
258f0 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
25900 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65   to 255 bytes, e
25910 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
25920 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  .** zero-termina
25930 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  tor.  Note that 
25940 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20  the name length 
25950 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65  limit is in byte
25960 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63  s, not.** charac
25970 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d  ters.  Any attem
25980 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
25990 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
259a0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
259b0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ll result in an 
259c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72  SQLITE_ERROR err
259d0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  or..**.** The th
259e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
259f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
25a00 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
25a10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
25a20 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
25a30 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61  akes. If this pa
25a40 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
25a50 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ive, then the SQ
25a60 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
25a70 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
25a80 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
25a90 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
25aa0 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
25ab0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
25ac0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
25ad0 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  t .** [SQLITE_UT
25ae0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
25af0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
25b00 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
25b10 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
25b20 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75  ers.  Any SQL fu
25b30 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
25b40 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ation should be 
25b50 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
25b60 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c  work with UTF-8,
25b70 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
25b80 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
25b90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25ba0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
25bb0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
25bc0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
25bd0 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69  n another.  It i
25be0 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20  s allowed to.** 
25bf0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
25c00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
25c10 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
25c20 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
25c30 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
25c40 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
25c50 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
25c60 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
25c70 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
25c80 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  ** When multiple
25c90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
25ca0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
25cb0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
25cc0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
25cd0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
25ce0 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
25cf0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
25d00 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
25d10 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
25d20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
25d30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25d40 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
25d50 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74  are what.** text
25d60 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
25d70 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
25d80 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
25d90 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  ld be.** [SQLITE
25da0 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  _ANY]..**.** The
25db0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
25dc0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
25dd0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
25de0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
25df0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
25e00 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
25e10 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
25e20 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
25e30 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
25e40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e  .**.** The seven
25e50 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e  th, eighth and n
25e60 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  inth parameters,
25e70 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
25e80 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
25e90 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
25ea0 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
25eb0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
25ec0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
25ed0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
25ee0 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20  e. A scalar SQL 
25ef0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
25f00 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
25f10 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46  ion of.** the xF
25f20 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  unc callback onl
25f30 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y, NULL pointers
25f40 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
25f50 64 20 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a  d as the xStep.*
25f60 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72  * and xFinal par
25f70 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72  ameters. An aggr
25f80 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
25f90 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
25fa0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
25fb0 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78 46   of xStep and xF
25fc0 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68  inal and NULL sh
25fd0 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66  ould be passed f
25fe0 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c  or xFunc. To del
25ff0 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69  ete an.** existi
26000 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ng SQL function 
26010 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
26020 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20  ss NULL for all 
26030 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
26040 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  * callback..**.*
26050 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65  * It is permitte
26060 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
26070 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
26080 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
26090 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
260a0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
260b0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
260c0 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
260d0 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
260e0 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
260f0 67 20 70 65 72 66 65 72 72 65 64 20 74 65 78 74  g perferred text
26100 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c   encodings.  SQL
26110 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
26120 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
26130 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  on most closely 
26140 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
26150 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
26160 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
26170 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  used..**.** INVA
26180 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
26190 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  16103} The [sqli
261a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
261b0 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66 61  ion16()] interfa
261c0 63 65 20 62 65 68 61 76 65 73 20 65 78 61 63 74  ce behaves exact
261d0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  ly.**          l
261e0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  ike [sqlite3_cre
261f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
26200 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78 63  in every way exc
26210 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20  ept that it.**  
26220 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72 65          interpre
26230 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f 6e  ts the zFunction
26240 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61 73  Name argument as
26250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
26260 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
26270 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
26280 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
26290 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   as a.**        
262a0 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
262b0 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  d UTF-8..**.** {
262c0 46 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 73  F16106} A succes
262d0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
262e0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
262f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
26300 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
26310 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  N,E,...)] interf
26320 61 63 65 20 72 65 67 69 73 74 65 72 73 0a 2a 2a  ace registers.**
26330 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65 70            or rep
26340 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 66  laces callback f
26350 75 6e 63 74 69 6f 6e 73 20 69 6e 20 5b 64 61 74  unctions in [dat
26360 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26370 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] D.**          
26380 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
26390 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
263a0 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20  on named X with 
263b0 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
263c0 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76           and hav
263d0 69 6e 67 20 61 20 70 65 72 66 65 72 72 65 64 20  ing a perferred 
263e0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66  text encoding of
263f0 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30   E..**.** {F1610
26400 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  9} A successful 
26410 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26420 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26430 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
26440 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  )].**          r
26450 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46  eplaces the P, F
26460 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65  , S, and L value
26470 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72  s from any prior
26480 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20   calls with.**  
26490 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
264a0 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20   D, X, N, and E 
264b0 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  values..**.** {F
264c0 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  16112} The [sqli
264d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
264e0 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e  ion(D,X,...)] in
264f0 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
26500 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
26510 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20   return code of 
26520 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
26530 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
26540 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20  on name X is.** 
26550 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20           longer 
26560 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65  than 255 bytes e
26570 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
26580 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
26590 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 38 7d 20  .**.** {F16118} 
265a0 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 65  Either F must be
265b0 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20   NULL and S and 
265c0 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f  L are non-NULL o
265d0 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20  r else F.**     
265e0 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c       is non-NULL
265f0 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
26600 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65   NULL, otherwise
26610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
26620 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26630 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
26640 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20  F,S,L)] returns 
26650 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a  [SQLITE_ERROR]..
26660 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 31 7d 20 54  **.** {F16121} T
26670 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
26680 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e  te_function(D,..
26690 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61  .)] interface fa
266a0 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20  ils with an.**  
266b0 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f          error co
266c0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55  de of [SQLITE_BU
266d0 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69  SY] if there exi
266e0 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  st [prepared sta
266f0 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20  tements].**     
26700 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20       associated 
26710 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
26720 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
26730 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 34 7d  ..**.** {F16124}
26740 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
26750 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
26760 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  X,N,...)] interf
26770 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61  ace fails with a
26780 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72  n.**          er
26790 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
267a0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61  ITE_ERROR] if pa
267b0 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69  rameter N (speci
267c0 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72  fying the number
267d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
267e0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
267f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65   SQL function be
26800 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 20  ing registered) 
26810 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  is less.**      
26820 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67      than -1 or g
26830 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e  reater than 127.
26840 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 37 7d 20  .**.** {F16127} 
26850 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  When N is non-ne
26860 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c  gative, the [sql
26870 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26880 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
26890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
268a0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61  erface causes ca
268b0 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e  llbacks to be in
268c0 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51  voked for the SQ
268d0 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
268e0 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77         named X w
268f0 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  hen the number o
26900 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  f arguments to t
26910 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
26920 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
26930 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20  xactly N..**.** 
26940 7b 46 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20  {F16130} When N 
26950 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69  is -1, the [sqli
26960 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26970 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
26980 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
26990 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
269a0 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
269b0 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c  oked for the SQL
269c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
269d0 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69        named X wi
269e0 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  th any number of
269f0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
26a00 2a 20 7b 46 31 36 31 33 33 7d 20 57 68 65 6e 20  * {F16133} When 
26a10 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
26a20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26a30 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  n(D,X,N,...)].**
26a40 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
26a50 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
26a60 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
26a70 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
26a80 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  X.**          an
26a90 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65  d when one imple
26aa0 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e  mentation has N>
26ab0 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  =0 and the other
26ac0 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20   has N=(-1).**  
26ad0 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c          the impl
26ae0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
26af0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20  a non-zero N is 
26b00 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a  preferred..**.**
26b10 20 7b 46 31 36 31 33 36 7d 20 57 68 65 6e 20 63   {F16136} When c
26b20 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
26b30 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26b40 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a  (D,X,N,E,...)].*
26b50 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69  *          speci
26b60 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  fy multiple impl
26b70 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
26b80 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
26b90 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20   X with.**      
26ba0 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d      the same num
26bb0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
26bc0 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66   N but with diff
26bd0 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  erent.**        
26be0 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74    encodings E, t
26bf0 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  hen the implemen
26c00 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d  tation where E m
26c10 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20  atches the.**   
26c20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
26c30 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66  encoding is pref
26c40 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  erred..**.** {F1
26c50 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67  6139} For an agg
26c60 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
26c70 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e  ion created usin
26c80 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
26c90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26ca0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
26cb0 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e  ,0,S,L)] the fin
26cc0 69 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  ializer.**      
26cd0 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77      function L w
26ce0 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e  ill always be in
26cf0 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  voked exactly on
26d00 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ce if the.**    
26d10 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74        step funct
26d20 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20  ion S is called 
26d30 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
26d40 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 34 32  s..**.** {F16142
26d50 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  } When SQLite in
26d60 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65  vokes either the
26d70 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20   xFunc or xStep 
26d80 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  function of.**  
26d90 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69          an appli
26da0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
26db0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
26dc0 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64  ggregate created
26dd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
26de0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
26df0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b  function()] or [
26e00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26e10 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a  unction16()],.**
26e20 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
26e30 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c  he array of [sql
26e40 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26e50 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68  cts passed as th
26e60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
26e70 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  ird parameter ar
26e80 65 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63  e always [protec
26e90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26ea0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69  e] objects..*/.i
26eb0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
26ec0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
26ed0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
26ee0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
26ef0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
26f00 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
26f10 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
26f20 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
26f30 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
26f40 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
26f50 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
26f60 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
26f70 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
26f80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
26f90 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
26fa0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
26fb0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
26fc0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26fd0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
26fe0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
26ff0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
27000 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
27010 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
27020 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
27030 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
27040 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
27050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
27060 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
27070 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
27080 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
27090 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
270a0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
270b0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a  3_context*).);..
270c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
270d0 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b  Text Encodings {
270e0 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10267}.**.** Th
270f0 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
27100 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
27110 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
27120 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
27130 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
27140 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
27150 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
27160 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
27170 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
27180 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
27190 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
271a0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
271b0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
271c0 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
271d0 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
271e0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
271f0 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
27200 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
27210 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
27220 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27230 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
27240 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
27250 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
27260 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
27270 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
27280 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
27290 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e  EF: Obsolete Fun
272a0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
272b0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
272c0 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74   all now obsolet
272d0 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  e.  In order to 
272e0 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
272f0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
27300 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
27310 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65  ode, we continue
27320 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74   to support.** t
27330 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
27340 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65   However, new de
27350 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63  velopment projec
27360 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ts should avoid.
27370 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
27380 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
27390 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
273a0 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
273b0 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
273c0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
273d0 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
273e0 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68  tell you want th
273f0 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ey do..*/.int sq
27400 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27410 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
27420 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  ntext*);.int sql
27430 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
27440 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
27450 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
27460 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
27470 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
27480 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71  3_stmt*);.int sq
27490 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
274a0 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64  over(void);.void
274b0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
274c0 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69  cleanup(void);.i
274d0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
274e0 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
274f0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
27500 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
27510 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
27520 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27530 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
27540 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
27550 20 56 61 6c 75 65 73 20 7b 46 31 35 31 30 30 7d   Values {F15100}
27560 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
27570 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
27580 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
27590 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
275a0 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
275b0 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
275c0 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
275d0 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
275e0 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
275f0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
27600 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
27610 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
27620 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
27630 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
27640 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
27650 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
27660 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27670 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
27680 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27690 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
276a0 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
276b0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
276c0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
276d0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
276e0 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61  .** The 4th para
276f0 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
27700 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
27710 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
27720 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
27730 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
27740 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
27750 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
27760 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
27770 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
27780 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
27790 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
277a0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
277b0 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
277c0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
277d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
277e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
277f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
27800 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
27810 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27820 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
27830 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
27840 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
27850 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
27860 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27870 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
27880 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
27890 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
278a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
278b0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
278c0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
278d0 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69  onding .** [sqli
278e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20  te3_column_blob 
278f0 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
27900 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63  _* routines] exc
27910 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65  ept that .** the
27920 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
27930 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
27940 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27950 75 65 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  ue] object point
27960 65 72 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66  er.** instead of
27970 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d   an [sqlite3_stm
27980 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
27990 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
279a0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
279b0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
279c0 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
279d0 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
279e0 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF16 string.** 
279f0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
27a00 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
27a10 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54  host machine.  T
27a20 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
27a30 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
27a40 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
27a50 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
27a60 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
27a70 74 20 55 54 46 31 36 20 73 74 72 69 6e 67 73 20  t UTF16 strings 
27a80 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
27a90 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
27aa0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
27ab0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27ac0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
27ad0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
27ae0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
27af0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
27b00 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
27b10 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
27b20 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
27b30 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
27b40 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
27b50 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
27b60 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
27b70 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
27b80 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
27b90 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
27ba0 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
27bb0 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
27bc0 72 64 73 20 69 66 20 74 68 65 20 76 61 6c 75 65  rds if the value
27bd0 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
27be0 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
27bf0 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
27c00 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
27c10 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73   done.  Otherwis
27c20 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
27c30 6f 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a  occurs.  The .**
27c40 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
27c50 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
27c60 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
27c70 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
27c80 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
27c90 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
27ca0 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
27cb0 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  t the pointer th
27cc0 61 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  at.** is returne
27cd0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
27ce0 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
27cf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27d00 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
27d10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27d20 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
27d30 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
27d40 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
27d50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
27d60 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
27d70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
27d80 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
27d90 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
27da0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
27db0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20  alue_text16()]. 
27dc0 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f   .**.** These ro
27dd0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
27de0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
27df0 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
27e00 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
27e10 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
27e20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
27e30 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
27e40 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  .**.**.** INVARI
27e50 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ANTS:.**.** {F15
27e60 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  103} The [sqlite
27e70 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d  3_value_blob(V)]
27e80 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
27e90 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
27ea0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
27eb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27ec0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 62 6c  ject V into a bl
27ed0 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  ob and then retu
27ee0 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  rns a.**        
27ef0 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65    pointer to the
27f00 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65   converted value
27f10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 36 7d  ..**.** {F15106}
27f20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
27f30 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e  lue_bytes(V)] in
27f40 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27f50 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
27f60 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
27f70 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73  in the blob or s
27f80 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
27f90 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
27fa0 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
27fb0 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
27fc0 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
27fd0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
27fe0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
27ff0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
28000 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
28010 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  V)] or.**       
28020 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75     [sqlite3_valu
28030 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a  e_text(V)]..**.*
28040 2a 20 7b 46 31 35 31 30 39 7d 20 54 68 65 20 5b  * {F15109} The [
28050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
28060 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66  tes16(V)] interf
28070 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
28080 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
28090 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
280a0 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  he string (exclu
280b0 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
280c0 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
280d0 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
280e0 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
280f0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
28100 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
28110 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
28120 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
28130 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20  ext16(V)],.**   
28140 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
28150 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
28160 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
28170 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56  value_text16le(V
28180 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31  )]..**.** {F1511
28190 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
281a0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d  value_double(V)]
281b0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
281c0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
281d0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
281e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
281f0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c  ject V into a fl
28200 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
28210 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ue and.**       
28220 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
28230 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e  y of that value.
28240 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35 7d 20  .**.** {F15115} 
28250 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
28260 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72  ue_int(V)] inter
28270 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
28280 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
28290 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
282a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
282b0 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
282c0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
282d0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
282e0 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20  turns the lower 
282f0 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20  32 bits of that 
28300 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
28310 46 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c  F15118} The [sql
28320 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
28330 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
28340 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
28350 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
28360 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28370 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
28380 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
28390 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
283a0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
283b0 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69  a copy of that i
283c0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nteger..**.** {F
283d0 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  15121} The [sqli
283e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56  te3_value_text(V
283f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
28400 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
28410 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
28420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
28430 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
28440 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
28450 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20  UTF-8 .**       
28460 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
28470 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
28480 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
28490 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d 20 54  **.** {F15124} T
284a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
284b0 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74  e_text16(V)] int
284c0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
284d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
284e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
284f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
28500 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
28510 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
28520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
28530 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  gned UTF-16 nati
28540 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
28550 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
28560 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
28570 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
28580 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
28590 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  5127} The [sqlit
285a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
285b0 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
285c0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
285d0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
285e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
285f0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
28600 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
28610 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
28620 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
28630 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a  F-16 big-endian.
28640 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
28650 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
28660 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
28670 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
28680 46 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c  F15130} The [sql
28690 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
286a0 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  6le(V)] interfac
286b0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
286c0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
286d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
286e0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
286f0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
28700 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
28710 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
28720 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
28730 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
28740 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
28750 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
28760 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
28770 0a 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54 68 65  .** {F15133} The
28780 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28790 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61  type(V)] interfa
287a0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
287b0 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53         one of [S
287c0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51  QLITE_NULL], [SQ
287d0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b  LITE_INTEGER], [
287e0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a  SQLITE_FLOAT],.*
287f0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
28800 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51  TE_TEXT], or [SQ
28810 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70  LITE_BLOB] as ap
28820 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a  propriate for.**
28830 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
28840 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28850 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ject V..**.** {F
28860 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  15136} The [sqli
28870 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
28880 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72  c_type(V)] inter
28890 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  face converts.**
288a0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
288b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
288c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
288d0 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20   into either an 
288e0 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20  integer or.**   
288f0 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e         a floatin
28900 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66  g point value if
28910 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69   it can do so wi
28920 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a  thout loss of.**
28930 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d            inform
28940 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72  ation, and retur
28950 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  ns one of [SQLIT
28960 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20  E_NULL],.**     
28970 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54       [SQLITE_INT
28980 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
28990 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
289a0 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  EXT], or.**     
289b0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f       [SQLITE_BLO
289c0 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
289d0 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
289e0 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64    the [protected
289f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
28a00 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74  object V after t
28a10 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74  he conversion at
28a20 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  tempt..*/.const 
28a30 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
28a40 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
28a50 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
28a60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
28a70 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
28a80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
28a90 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
28aa0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
28ab0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
28ac0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
28ad0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
28ae0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
28af0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
28b00 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
28b10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
28b20 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
28b30 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
28b40 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
28b50 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
28b60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
28b70 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
28b80 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
28b90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28ba0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28bb0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
28bc0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
28bd0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
28be0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28bf0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
28c00 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
28c10 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
28c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
28c40 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
28c50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28c60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28c70 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
28c80 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
28c90 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a 2a  xt {F16210}.**.*
28ca0 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * The implementa
28cb0 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74  tion of aggregat
28cc0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
28cd0 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  use this routine
28ce0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20   to allocate.** 
28cf0 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  a structure for 
28d00 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
28d10 61 74 65 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69  ate.  .** The fi
28d20 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
28d30 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
28d40 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65  ontext() routine
28d50 20 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64   is.** is called
28d60 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
28d70 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c  r aggregate, SQL
28d80 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42  ite allocates nB
28d90 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ytes of memory.*
28da0 2a 20 7a 65 72 6f 73 20 74 68 61 74 20 6d 65 6d  * zeros that mem
28db0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
28dc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
28dd0 2e 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64 20 61  ..** On second a
28de0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
28df0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
28e00 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
28e10 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
28e20 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
28e30 63 74 69 6f 6e 20 69 6e 64 65 78 2c 20 74 68 65  ction index, the
28e40 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
28e50 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
28e60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
28e70 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ** of the aggreg
28e80 61 74 65 20 63 61 6e 20 75 73 65 20 74 68 65 20  ate can use the 
28e90 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20  returned buffer 
28ea0 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61  to accumulate da
28eb0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ta..**.** SQLite
28ec0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
28ed0 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74  rees the allocat
28ee0 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74  ed buffer when t
28ef0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
28f00 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
28f10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
28f20 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
28f30 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  d be a copy of t
28f40 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
28f50 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
28f60 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
28f70 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
28f80 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  t.** parameter t
28f90 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  o the callback r
28fa0 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
28fb0 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
28fc0 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
28fd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
28fe0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
28ff0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
29000 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
29010 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
29020 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
29030 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
29040 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
29050 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 68 65  .** {F16211} The
29060 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f   first invocatio
29070 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67  n of [sqlite3_ag
29080 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
29090 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20  C,N)] for.**    
290a0 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c        a particul
290b0 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61  ar instance of a
290c0 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  n aggregate func
290d0 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74  tion (for a part
290e0 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20  icular.**       
290f0 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61     context C) ca
29100 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61  uses SQLite to a
29110 6c 6c 6f 63 61 74 69 6f 6e 20 4e 20 62 79 74 65  llocation N byte
29120 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  s of memory,.** 
29130 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68           zero th
29140 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
29150 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
29160 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  to the allocatio
29170 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
29180 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  memory..**.** {F
29190 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f  16213} If a memo
291a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
291b0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
291c0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
291d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
291e0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74  _context(C,N)] t
291f0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
29200 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a   returns 0..**.*
29210 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63 6f 6e  * {F16215} Secon
29220 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
29230 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a   invocations of.
29240 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
29250 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
29260 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72  ontext(C,N)] for
29270 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78   the same contex
29280 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20  t pointer C.**  
29290 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74          ignore t
292a0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61  he N parameter a
292b0 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  nd return a poin
292c0 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a  ter to the same.
292d0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63  **          bloc
292e0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75  k of memory retu
292f0 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73  rned by the firs
29300 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  t invocation..**
29310 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54 68 65  .** {F16217} The
29320 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
29330 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67  d by [sqlite3_ag
29340 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
29350 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  C,N)] is.**     
29360 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c       automatical
29370 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20  ly freed on the 
29380 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  next call to [sq
29390 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
293a0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
293b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
293c0 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  )] for the [prep
293d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
293e0 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20  containing.**   
293f0 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65         the aggre
29400 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73  gate function as
29410 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f  sociated with co
29420 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64  ntext C..*/.void
29430 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
29440 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
29450 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
29460 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
29470 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
29480 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
29490 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a  ons {F16240}.**.
294a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
294b0 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
294c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
294d0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
294e0 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
294f0 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
29500 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
29510 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
29520 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 74 65   the the [sqlite
29530 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29540 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
29550 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29560 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
29570 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
29580 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
29590 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
295a0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
295b0 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  n. {END}.**.** T
295c0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
295d0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
295e0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
295f0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
29600 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29610 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
29620 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
29630 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
29640 20 7b 46 31 36 32 34 33 7d 20 54 68 65 20 5b 73   {F16243} The [s
29650 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
29660 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (C)] interface r
29670 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
29680 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
29690 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20   P pointer from 
296a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
296b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
296c0 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a  ,N,E,P,F,S,L)].*
296d0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
296e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
296f0 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45  nction16(D,X,N,E
29700 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20  ,P,F,S,L)] call 
29710 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
29720 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
29730 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  SQL function ass
29740 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
29750 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
29760 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a  e3_context] C..*
29770 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
29780 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
29790 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
297a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
297b0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
297c0 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  n For Functions 
297d0 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16250}.**.** T
297e0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
297f0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
29800 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29810 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
29820 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
29830 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29840 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
29850 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
29860 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 74 65   the the [sqlite
29870 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29880 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
29890 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
298a0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
298b0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
298c0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
298d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
298e0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
298f0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  n..**.** INVARIA
29900 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  NTS:.**.** {F162
29910 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  53} The [sqlite3
29920 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
29930 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  le(C)] interface
29940 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
29950 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
29960 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f     D pointer fro
29970 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  m the [sqlite3_c
29980 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
29990 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
299a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
299b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
299c0 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e  function16(D,X,N
299d0 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c  ,E,P,F,S,L)] cal
299e0 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  l that.**       
299f0 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68     registered th
29a00 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
29a10 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a  ssociated with .
29a20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
29a30 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e  ite3_context] C.
29a40 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
29a50 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
29a60 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
29a70 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
29a80 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
29a90 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
29aa0 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a  ta {F16270}.**.*
29ab0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
29ac0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
29ad0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
29ae0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
29af0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
29b00 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68  e meta-data with
29b10 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
29b20 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
29b30 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
29b40 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
29b50 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
29b60 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
29b70 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
29b80 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
29b90 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
29ba0 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
29bb0 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d  ated meta-data m
29bc0 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
29bd0 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
29be0 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
29bf0 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
29c00 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
29c10 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
29c20 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
29c30 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
29c40 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
29c50 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
29c60 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d  ored as.** meta-
29c70 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
29c80 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
29c90 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
29ca0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
29cb0 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
29cc0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
29cd0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
29ce0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
29cf0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
29d00 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
29d10 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
29d20 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
29d30 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
29d40 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
29d50 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
29d60 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
29d70 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
29d80 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
29d90 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
29da0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
29db0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
29dc0 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  -data.** associa
29dd0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
29de0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
29df0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
29e00 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
29e10 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
29e20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29e30 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
29e40 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61   If no meta-data
29e50 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 20 62   has been ever b
29e60 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
29e70 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  Nth.** argument 
29e80 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
29e90 20 6f 72 20 69 66 20 74 68 65 20 63 6f 6f 72 65   or if the coore
29ea0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
29eb0 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 68  n parameter.** h
29ec0 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
29ed0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
29ee0 61 73 20 73 65 74 2c 20 74 68 65 6e 20 73 71 6c  as set, then sql
29ef0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
29f00 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
29f10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
29f20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29f30 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
29f40 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
29f50 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 70  e meta-data.** p
29f60 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
29f70 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
29f80 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  s the meta-data 
29f90 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
29fa0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
29fb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29fc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
29fd0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
29fe0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
29ff0 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
2a000 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
2a010 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
2a020 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
2a030 79 65 64 2e 20 0a 2a 2a 20 49 66 20 69 74 20 69  yed. .** If it i
2a040 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
2a050 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2a060 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 0a 2a  he destructor .*
2a070 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
2a080 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
2a090 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2a0a0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
2a0b0 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 2d 64 61  n.** the meta-da
2a0c0 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
2a0d0 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
2a0e0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
2a0f0 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
2a100 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2a110 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
2a120 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
2a130 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
2a140 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
2a150 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2a160 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 2d 64 61  and drop meta-da
2a170 74 61 20 6f 6e 0a 2a 2a 20 61 6e 79 20 70 61 72  ta on.** any par
2a180 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
2a190 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
2a1a0 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75  me.  The only gu
2a1b0 61 72 61 6e 74 65 65 0a 2a 2a 20 69 73 20 74 68  arantee.** is th
2a1c0 61 74 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  at the destructo
2a1d0 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
2a1e0 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
2a1f0 64 61 74 61 20 69 73 0a 2a 2a 20 64 72 6f 70 70  data is.** dropp
2a200 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61  ed..**.** In pra
2a210 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61  ctice, meta-data
2a220 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
2a230 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
2a240 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
2a250 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
2a260 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
2a270 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
2a280 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
2a290 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53  .** values and S
2a2a0 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a  QL variables..**
2a2b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2a2c0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2a2d0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2a2e0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2a2f0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2a300 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2a310 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2a320 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 32 7d  :.**.** {F16272}
2a330 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65   The [sqlite3_ge
2a340 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20  t_auxdata(C,N)] 
2a350 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a360 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  s a pointer.**  
2a370 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64          to metad
2a380 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
2a390 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 61  ith the Nth para
2a3a0 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c  meter of the SQL
2a3b0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2a3c0 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74        whose cont
2a3d0 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c  ext is C, or NUL
2a3e0 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
2a3f0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2a400 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
2a410 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61 6d   with that param
2a420 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  eter..**.** {F16
2a430 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  274} The [sqlite
2a440 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
2a450 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  N,P,D)] interfac
2a460 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61  e assigns a meta
2a470 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  data.**         
2a480 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68   pointer P to th
2a490 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20  e Nth parameter 
2a4a0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2a4b0 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74  ion with context
2a4c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a  .**          C..
2a4d0 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 36 7d 20 53  **.** {F16276} S
2a4e0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
2a4f0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
2a500 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
2a510 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
2a520 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74        which is t
2a530 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e  he metadata poin
2a540 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20  ter P following 
2a550 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
2a560 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
2a570 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
2a580 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65  ,D)] when SQLite
2a590 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a   ceases to hold.
2a5a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2a5b0 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  metadata..**.** 
2a5c0 7b 46 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20  {F16277} SQLite 
2a5d0 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d  ceases to hold m
2a5e0 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53  etadata for an S
2a5f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  QL function para
2a600 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
2a610 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65    when the value
2a620 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74   of that paramet
2a630 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  er changes..**.*
2a640 2a 20 7b 46 31 36 32 37 38 7d 20 57 68 65 6e 20  * {F16278} When 
2a650 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2a660 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
2a670 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64  s invoked, the d
2a680 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20  estructor.**    
2a690 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20        is called 
2a6a0 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65  for any prior me
2a6b0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
2a6c0 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
2a6d0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2a6e0 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61       context C a
2a6f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a  nd parameter N..
2a700 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 39 7d 20 53  **.** {F16279} S
2a710 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20  QLite will call 
2a720 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  destructors for 
2a730 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20  any metadata it 
2a740 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20  is holding.**   
2a750 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74         in a part
2a760 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64  icular [prepared
2a770 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68   statement] S wh
2a780 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  en either.**    
2a790 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2a7a0 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c  eset(S)] or [sql
2a7b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2a7c0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a  ] is called..*/.
2a7d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
2a7e0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2a7f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2a800 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
2a810 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
2a820 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2a830 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
2a840 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
2a850 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a860 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
2a870 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
2a880 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20  ructor Behavior 
2a890 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10280}.**.** T
2a8a0 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
2a8b0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 64   value for the d
2a8c0 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
2a8d0 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
2a8e0 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
2a8f0 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
2a900 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
2a910 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
2a920 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
2a930 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
2a940 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
2a950 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
2a960 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
2a970 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
2a980 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
2a990 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
2a9a0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2a9b0 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 20  destroyed.  The 
2a9c0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
2a9d0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
2a9e0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
2a9f0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
2aa00 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
2aa10 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
2aa20 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
2aa30 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
2aa40 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
2aa50 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
2aa60 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
2aa70 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
2aa80 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
2aa90 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
2aaa0 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
2aab0 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
2aac0 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
2aad0 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
2aae0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
2aaf0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2ab00 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
2ab10 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
2ab20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
2ab30 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
2ab40 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
2ab50 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
2ab60 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2ab70 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
2ab80 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
2ab90 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
2aba0 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
2abb0 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a 2a  n {F16400}.**.**
2abc0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2abd0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
2abe0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
2abf0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
2ac00 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
2ac10 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2ac20 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
2ac30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2ac40 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2ac50 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2ac60 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2ac70 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
2ac80 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
2ac90 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2aca0 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
2acb0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a  uch like the .**
2acc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2acd0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2ace0 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20  nd_*] family of 
2acf0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a  functions used.*
2ad00 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  * to bind values
2ad10 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
2ad20 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
2ad30 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
2ad40 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  efer to the.** [
2ad50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ad60 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2ad70 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  _* documentation
2ad80 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  ] for.** additio
2ad90 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2ada0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2adb0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2adc0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2add0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
2ade0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
2adf0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
2ae00 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
2ae10 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
2ae20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
2ae30 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
2ae40 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
2ae50 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
2ae60 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
2ae70 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
2ae80 65 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 73 71  eter. .** The sq
2ae90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
2aea0 6f 62 6c 6f 62 28 29 20 69 6e 65 72 66 61 63 65  oblob() inerface
2aeb0 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
2aec0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2aed0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2aee0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2aef0 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
2af00 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
2af10 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
2af20 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
2af30 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2af40 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2af50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2af60 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2af70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
2af80 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
2af90 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
2afa0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
2afb0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
2afc0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2afd0 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
2afe0 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
2aff0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
2b000 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b010 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
2b020 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2b030 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
2b040 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
2b050 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
2b060 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
2b070 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c  xception..** SQL
2b080 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
2b090 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
2b0a0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
2b0b0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
2b0c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2b0d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2b0e0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
2b0f0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
2b100 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
2b110 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72    SQLite interpr
2b120 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
2b130 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
2b140 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2b150 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
2b160 54 46 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69  TF8. SQLite.** i
2b170 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
2b180 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2b190 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2b1a0 28 29 20 61 73 20 55 54 46 31 36 20 69 6e 20 6e  () as UTF16 in n
2b1b0 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
2b1c0 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69  der.  If the thi
2b1d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2b1e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b1f0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
2b200 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b210 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
2b220 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2b230 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
2b240 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
2b250 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
2b260 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
2b270 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20  haracter..** If 
2b280 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2b290 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
2b2a0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
2b2b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2b2c0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
2b2d0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
2b2e0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
2b2f0 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
2b300 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
2b310 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
2b320 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
2b330 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
2b340 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2b350 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2b360 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2b370 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
2b380 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 63 6f  utines make a co
2b390 70 79 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  py private copy 
2b3a0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
2b3b0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
2b3c0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
2b3d0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
2b3e0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
2b3f0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
2b400 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
2b410 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
2b420 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
2b430 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  m..** The sqlite
2b440 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
2b450 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
2b460 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
2b470 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
2b480 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
2b490 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
2b4a0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
2b4b0 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a  n.  By default,.
2b4c0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
2b4d0 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
2b4e0 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74  R.  A subsequent
2b4f0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2b500 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2b510 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2b520 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
2b530 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
2b540 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
2b550 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  RROR..**.** The 
2b560 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2b570 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
2b580 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 0a  e causes SQLite.
2b590 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  ** to throw an e
2b5a0 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
2b5b0 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
2b5c0 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67   BLOB is to long
2b5d0 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74  .** to represent
2b5e0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  .  The sqlite3_r
2b5f0 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e  esult_nomem() in
2b600 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 75 73 65  terface.** cause
2b610 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
2b620 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 69  w an exception i
2b630 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
2b640 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  he a.** memory a
2b650 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
2b660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2b670 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
2b680 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2b690 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2b6a0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2b6b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2b6c0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2b6d0 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
2b6e0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
2b6f0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
2b700 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  d argument..** T
2b710 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2b720 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
2b730 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2b740 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2b750 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2b760 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2b770 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
2b780 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2b790 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2b7a0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2b7b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
2b7c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2b7d0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
2b7e0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2b7f0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2b800 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b810 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2b820 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  e NULL..**.** Th
2b830 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b840 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
2b850 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
2b860 2c 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  , .** sqlite3_re
2b870 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
2b880 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
2b890 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
2b8a0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
2b8b0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2b8c0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
2b8d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2b8e0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
2b8f0 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
2b900 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
2b910 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
2b920 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2b930 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
2b940 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
2b950 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
2b960 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
2b970 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b  y..** SQLite tak
2b980 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
2b990 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
2b9a0 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
2b9b0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2b9c0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
2b9d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2b9e0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20  terfaces..** If 
2b9f0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2ba00 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2ba10 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2ba20 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
2ba30 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
2ba40 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
2ba50 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
2ba60 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 0a 2a  2nd parameter .*
2ba70 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
2ba80 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
2ba90 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  er..** If the 3r
2baa0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
2bab0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2bac0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2bad0 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
2bae0 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
2baf0 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
2bb00 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
2bb10 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
2bb20 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
2bb30 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
2bb40 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
2bb50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
2bb60 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
2bb70 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
2bb80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2bb90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2bba0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2bbb0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2bbc0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
2bbd0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
2bbe0 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
2bbf0 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
2bc00 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
2bc10 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
2bc20 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75  ext or blob resu
2bc30 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
2bc40 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
2bc50 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
2bc60 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
2bc70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2bc80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2bc90 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2bca0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2bcb0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2bcc0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2bcd0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
2bce0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73 73  en.** SQLite ass
2bcf0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
2bd00 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c  xt or blob resul
2bd10 74 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 73 70  t is constant sp
2bd20 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73 20  ace and.** does 
2bd30 6e 6f 74 20 63 6f 70 79 20 74 68 65 20 73 70 61  not copy the spa
2bd40 63 65 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  ce or call a des
2bd50 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20  tructor when it 
2bd60 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
2bd70 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2bd80 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
2bd90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2bda0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2bdb0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2bdc0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2bdd0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
2bde0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
2bdf0 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
2be00 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
2be10 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
2be20 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
2be30 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
2be40 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
2be50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2be60 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
2be70 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
2be80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2be90 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2bea0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2beb0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2bec0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2bed0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2bee0 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
2bef0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bf00 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
2bf10 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2bf20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
2bf30 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
2bf40 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
2bf50 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
2bf60 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
2bf70 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
2bf80 6f 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  o that [sqlite3_
2bf90 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
2bfa0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2bfb0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
2bfc0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
2bfd0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2bfe0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
2bff0 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
2c000 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65  arm..** A [prote
2c010 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c020 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
2c030 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
2c040 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
2c050 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c060 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
2c070 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
2c080 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
2c090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c0a0 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
2c0b0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
2c0c0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
2c0d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2c0e0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
2c0f0 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
2c100 65 6e 74 20 74 68 72 65 61 64 20 0a 2a 2a 20 74  ent thread .** t
2c110 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
2c120 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
2c130 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2c140 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
2c150 69 65 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  ieved.** the [sq
2c160 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
2c170 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
2c180 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2c190 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
2c1a0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  NTS:.**.** {F164
2c1b0 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  03} The default 
2c1c0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
2c1d0 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69  m any SQL functi
2c1e0 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  on is NULL..**.*
2c1f0 2a 20 7b 46 31 36 34 30 36 7d 20 54 68 65 20 5b  * {F16406} The [
2c200 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2c210 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  lob(C,V,N,D)] in
2c220 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2c230 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c240 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2c250 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2c260 20 61 20 62 6c 6f 62 20 74 68 61 74 20 69 73 20   a blob that is 
2c270 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20  N bytes.**      
2c280 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e      in length an
2c290 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70  d with content p
2c2a0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a  ointed to by V..
2c2b0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20 54  **.** {F16409} T
2c2c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2c2d0 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20  lt_double(C,V)] 
2c2e0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2c2f0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c300 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
2c310 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2c320 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  be the floating 
2c330 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a  point value V..*
2c340 2a 0a 2a 2a 20 7b 46 31 36 34 31 32 7d 20 54 68  *.** {F16412} Th
2c350 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2c360 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20  t_error(C,V,N)] 
2c370 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2c380 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
2c390 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
2c3a0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2c3b0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
2c3c0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
2c3d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2c3e0 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61  ITE_ERROR] and a
2c3f0 20 55 54 46 38 20 65 72 72 6f 72 20 6d 65 73 73   UTF8 error mess
2c400 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  age copied from 
2c410 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20  V up to the.**  
2c420 20 20 20 20 20 20 20 20 66 69 72 73 74 20 7a 65          first ze
2c430 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c  ro byte or until
2c440 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61   N bytes are rea
2c450 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  d if N is positi
2c460 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31  ve..**.** {F1641
2c470 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
2c480 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43  result_error16(C
2c490 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,V,N)] interface
2c4a0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
2c4b0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
2c4c0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2c4d0 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
2c4e0 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
2c4f0 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
2c500 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
2c510 5d 20 61 6e 64 20 61 20 55 54 46 31 36 20 6e 61  ] and a UTF16 na
2c520 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2c530 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
2c540 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 64            copied
2c550 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68   from V up to th
2c560 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
2c570 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c  minator or until
2c580 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
2c590 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69 66       are read if
2c5a0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a   N is positive..
2c5b0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 38 7d 20 54  **.** {F16418} T
2c5c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2c5d0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
2c5e0 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
2c5f0 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
2c600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
2c610 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
2c620 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
2c630 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
2c640 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
2c650 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42      [SQLITE_TOOB
2c660 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  IG] and an appro
2c670 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
2c680 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  sage..**.** {F16
2c690 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  421} The [sqlite
2c6a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
2c6b0 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61  omem(C)] interfa
2c6c0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
2c6d0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
2c6e0 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
2c6f0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2c700 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
2c710 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
2c720 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2c730 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61  _NOMEM] and an a
2c740 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
2c750 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
2c760 7b 46 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71  {F16424} The [sq
2c770 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2c780 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e  or_code(C,E)] in
2c790 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2c7a0 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
2c7b0 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
2c7c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
2c7d0 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
2c7e0 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
2c7f0 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e E..**         
2c800 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   The error messa
2c810 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68 61  ge text is uncha
2c820 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  nged..**.** {F16
2c830 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  427} The [sqlite
2c840 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56  3_result_int(C,V
2c850 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2c860 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2c870 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2c880 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2c890 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
2c8a0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56   integer value V
2c8b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 30 7d  ..**.** {F16430}
2c8c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2c8d0 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d  sult_int64(C,V)]
2c8e0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2c8f0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2c900 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2c910 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2c920 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 69   be the 64-bit i
2c930 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
2c940 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 33 7d 20 54  **.** {F16433} T
2c950 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2c960 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65  lt_null(C)] inte
2c970 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2c980 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2c990 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2c9a0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e  nction C to be N
2c9b0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ULL..**.** {F164
2c9c0 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
2c9d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
2c9e0 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
2c9f0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2ca00 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2ca10 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2ca20 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
2ca30 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  F8 string.**    
2ca40 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68        V up to th
2ca50 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
2ca60 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
2ca70 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
2ca80 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
2ca90 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  f V if N is non-
2caa0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
2cab0 7b 46 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71  {F16439} The [sq
2cac0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2cad0 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  t16(C,V,N,D)] in
2cae0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2caf0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2cb00 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2cb10 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2cb20 20 74 68 65 20 55 54 46 31 36 20 6e 61 74 69 76   the UTF16 nativ
2cb30 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
2cb40 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2cb50 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
2cb60 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a  t zero if N is.*
2cb70 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 61 74  *          negat
2cb80 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73 74  ive or the first
2cb90 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
2cba0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
2cbb0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34  ve..**.** {F1644
2cbc0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2cbd0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2cbe0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
2cbf0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
2cc00 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2cc10 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
2cc20 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
2cc30 20 55 54 46 31 36 20 62 69 67 2d 65 6e 64 69 61   UTF16 big-endia
2cc40 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
2cc50 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
2cc60 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
2cc70 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2cc80 69 73 20 6e 65 67 61 74 69 76 65 20 6f 72 20 74  is negative or t
2cc90 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
2cca0 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   or V if N is no
2ccb0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
2ccc0 2a 20 7b 46 31 36 34 34 35 7d 20 54 68 65 20 5b  * {F16445} The [
2ccd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2cce0 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
2ccf0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2cd00 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2cd10 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2cd20 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2cd30 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20 6c  o be the UTF16 l
2cd40 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20  ittle-endian.** 
2cd50 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2cd60 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
2cd70 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a  t zero if N is.*
2cd80 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 61 74  *          negat
2cd90 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73 74  ive or the first
2cda0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
2cdb0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
2cdc0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34  ve..**.** {F1644
2cdd0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
2cde0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56  result_value(C,V
2cdf0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2ce00 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2ce10 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2ce20 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2ce30 74 6f 20 62 65 20 5b 75 6e 70 72 6f 74 65 63 74  to be [unprotect
2ce40 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ce50 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  ].**          ob
2ce60 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ject V..**.** {F
2ce70 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  16451} The [sqli
2ce80 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2ce90 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66  lob(C,N)] interf
2cea0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
2ceb0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2cec0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
2ced0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
2cee0 4e 2d 62 79 74 65 20 62 6c 6f 62 20 6f 66 20 61  N-byte blob of a
2cef0 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20  ll zeros..**.** 
2cf00 7b 46 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71  {F16454} The [sq
2cf10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2cf20 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  or()] and [sqlit
2cf30 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2cf40 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
2cf50 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
2cf60 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72   a copy of their
2cf70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
2cf80 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a  trings before.**
2cf90 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2cfa0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ing..**.** {F164
2cfb0 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65 73  57} If the D des
2cfc0 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65  tructor paramete
2cfd0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  r to [sqlite3_re
2cfe0 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c  sult_blob(C,V,N,
2cff0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
2d000 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2d010 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _text(C,V,N,D)],
2d020 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2d030 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
2d040 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2d050 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d060 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
2d070 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
2d080 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
2d090 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
2d0a0 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73  ,D)] is the cons
2d0b0 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
2d0c0 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  TIC].**         
2d0d0 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63   then no destruc
2d0e0 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c  tor is ever call
2d0f0 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65  ed on the pointe
2d100 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a  r V and SQLite.*
2d110 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75 6d  *          assum
2d120 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d  es that V is imm
2d130 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  utable..**.** {F
2d140 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44 20  16460} If the D 
2d150 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
2d160 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2d170 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
2d180 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
2d190 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2d1a0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
2d1b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
2d1c0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
2d1d0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
2d1e0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
2d1f0 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
2d200 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
2d210 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2d220 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
2d230 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
2d240 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20  onstant.**      
2d250 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e      [SQLITE_TRAN
2d260 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20  SIENT] then the 
2d270 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73  interfaces makes
2d280 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2d290 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
2d2a0 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61  nt of V and reta
2d2b0 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a  ins the copy..**
2d2c0 0a 2a 2a 20 7b 46 31 36 34 36 33 7d 20 49 66 20  .** {F16463} If 
2d2d0 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
2d2e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2d2f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2d300 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
2d310 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2d320 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
2d330 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
2d340 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2d350 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
2d360 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2d370 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2d380 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
2d390 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d3a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2d3b0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
2d3c0 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65   some value othe
2d3d0 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
2d3e0 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73     the constants
2d3f0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
2d400 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41   and [SQLITE_TRA
2d410 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 0a 2a 2a  NSIENT] then .**
2d420 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
2d430 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
2d440 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
2d450 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79  th V as its only
2d460 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
2d470 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61        when it ha
2d480 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2d490 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a  the V value..*/.
2d4a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d4b0 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
2d4c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2d4d0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2d4e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2d4f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d500 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
2d510 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
2d520 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
2d530 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
2d540 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d550 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2d560 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d570 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
2d580 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d590 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2d5a0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2d5b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
2d5c0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
2d5d0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2d5e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2d5f0 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
2d600 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2d610 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2d620 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
2d630 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2d640 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d650 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
2d660 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2d670 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d680 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
2d690 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
2d6a0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
2d6b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d6c0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
2d6d0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
2d6e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2d6f0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
2d700 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2d710 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2d720 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2d730 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2d740 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
2d750 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2d760 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2d770 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2d780 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2d790 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
2d7a0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2d7b0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
2d7c0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2d7d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d7e0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
2d7f0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2d800 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2d810 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2d820 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2d830 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
2d840 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
2d850 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
2d860 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2d870 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2d880 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
2d890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2d8a0 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
2d8b0 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 46  ing Sequences {F
2d8c0 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16600}.**.** The
2d8d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
2d8e0 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77   used to add new
2d8f0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2d900 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nces to the.** [
2d910 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65  sqlite3*] handle
2d920 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
2d930 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2d940 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  . .**.** The nam
2d950 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c  e of the new col
2d960 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2d970 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
2d980 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
2d990 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
2d9a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2d9b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
2d9c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2d9d0 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
2d9e0 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71  16 string for sq
2d9f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2da00 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61  lation16(). In a
2da10 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
2da20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
2da30 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2da40 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2da50 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
2da60 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
2da70 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
2da80 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
2da90 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
2daa0 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49  TF16LE] or [SQLI
2dab0 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64  TE_UTF16BE], ind
2dac0 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
2dad0 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a   user-supplied.*
2dae0 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  * routine expect
2daf0 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70  s to be passed p
2db00 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
2db10 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  gs encoded using
2db20 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31   UTF-8,.** UTF-1
2db30 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  6 little-endian 
2db40 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
2db50 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
2db60 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  y. The.** third 
2db70 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61  argument might a
2db80 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  lso be [SQLITE_U
2db90 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f  TF16_ALIGNED] to
2dba0 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a   indicate that.*
2dbb0 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
2dbc0 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
2dbd0 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
2dbe0 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
2dbf0 20 6f 66 20 55 54 46 31 36 20 69 6e 20 74 68 65   of UTF16 in the
2dc00 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2dc10 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63  er of the host c
2dc20 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  omputer..**.** A
2dc30 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2dc40 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f  user supplied ro
2dc50 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61  utine must be pa
2dc60 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74  ssed as the fift
2dc70 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  h.** argument.  
2dc80 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
2dc90 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20  his is the same 
2dca0 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  as deleting the 
2dcb0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
2dcc0 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53  uence (so that S
2dcd0 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c  QLite cannot cal
2dce0 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a  l it anymore)..*
2dcf0 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20  * Each time the 
2dd00 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 73  application.** s
2dd10 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
2dd20 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
2dd30 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
2dd40 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61   of the void* pa
2dd50 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 66  ssed as.** the f
2dd60 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
2dd70 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2dd80 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a  _collation() or.
2dd90 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
2dda0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20  e_collation16() 
2ddb0 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
2ddc0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
2ddd0 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
2dde0 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
2ddf0 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
2de00 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
2de10 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
2de20 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
2de30 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
2de40 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
2de50 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
2de60 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
2de70 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
2de80 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
2de90 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
2dea0 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
2deb0 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
2dec0 7d 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  } The applicatio
2ded0 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  n defined collat
2dee0 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  ion routine shou
2def0 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67  ld.** return neg
2df00 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70  ative, zero or p
2df10 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68  ositive if.** th
2df20 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
2df30 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
2df40 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
2df50 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
2df60 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65  d.** string. i.e
2df70 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52  . (STRING1 - STR
2df80 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ING2)..**.** The
2df90 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2dfa0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
2dfb0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
2dfc0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2dfd0 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74  on().** excapt t
2dfe0 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20  hat it takes an 
2dff0 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77  extra argument w
2e000 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75  hich is a destru
2e010 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ctor for.** the 
2e020 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20  collation.  The 
2e030 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2e040 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f  lled when the co
2e050 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  llation is.** de
2e060 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70  stroyed and is p
2e070 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20  assed a copy of 
2e080 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2e090 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74  eter void* point
2e0a0 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  er.** of the sql
2e0b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2e0c0 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43  ation_v2()..** C
2e0d0 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65  ollations are de
2e0e0 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20  stroyed when.** 
2e0f0 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
2e100 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
2e110 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
2e120 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
2e130 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65  ctions.** or whe
2e140 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d  n the [sqlite3*]
2e150 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
2e160 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
2e170 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2e180 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
2e190 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
2e1a0 36 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  603} A successfu
2e1b0 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a  l call to the.**
2e1c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2e1d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e1e0 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
2e1f0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  ,D)] interface.*
2e200 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
2e210 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 46 20  ters function F 
2e220 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  as the compariso
2e230 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 20  n function used 
2e240 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  to.**          i
2e250 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69  mplement collati
2e260 6f 6e 20 58 20 6f 6e 20 5b 64 61 74 61 62 61 73  on X on [databas
2e270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
2e280 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2e290 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e 67  databases having
2e2a0 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a   encoding E..**.
2e2b0 2a 2a 20 7b 46 31 36 36 30 34 7d 20 53 51 4c 69  ** {F16604} SQLi
2e2c0 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74  te understands t
2e2d0 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
2e2e0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
2e2f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2e300 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
2e310 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65  ,P,F,D)] as a ze
2e320 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2e330 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
2e340 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20  string in which 
2e350 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20  case is ignored 
2e360 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61 63  for ASCII charac
2e370 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ters and.**     
2e380 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69 63       is signific
2e390 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49  ant for non-ASCI
2e3a0 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  I characters..**
2e3b0 0a 2a 2a 20 7b 46 31 36 36 30 36 7d 20 53 75 63  .** {F16606} Suc
2e3c0 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f  cessive calls to
2e3d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e3e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
2e3f0 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
2e400 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
2e410 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72   same values for
2e420 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76   B, X, and E, ov
2e430 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c  erride prior val
2e440 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
2e450 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a  of P, F, and D..
2e460 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 39 7d 20 54  **.** {F16609} T
2e470 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
2e480 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
2e490 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2e4a0 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
2e4b0 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74            is not
2e4c0 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73   NULL then it is
2e4d0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67   called with arg
2e4e0 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65  ument P when the
2e4f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
2e500 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2e510 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53 51  is dropped by SQ
2e520 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  Lite..**.** {F16
2e530 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67  612} A collating
2e540 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
2e550 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  pped when it is 
2e560 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a  overloaded..**.*
2e570 2a 20 7b 46 31 36 36 31 35 7d 20 41 20 63 6f 6c  * {F16615} A col
2e580 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2e590 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20  is dropped when 
2e5a0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e5b0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
2e5c0 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73      is closed us
2e5d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
2e5e0 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  se()]..**.** {F1
2e5f0 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65  6618} The pointe
2e600 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r P in [sqlite3_
2e610 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2e620 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
2e630 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
2e640 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
2e650 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
2e660 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
2e670 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
2e680 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20       function F 
2e690 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65  for all subseque
2e6a0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
2e6b0 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  f F..**.** {F166
2e6c0 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  21} A call to [s
2e6d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2e6e0 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c  llation(B,X,E,P,
2e6f0 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a  F)] is exactly.*
2e700 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
2e710 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f  ame as a call to
2e720 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e730 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
2e740 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
2e750 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d    the same param
2e760 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c  eters and a NULL
2e770 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a   destructor..**.
2e780 2a 2a 20 7b 46 31 36 36 32 34 7d 20 46 6f 6c 6c  ** {F16624} Foll
2e790 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33  owing a [sqlite3
2e7a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2e7b0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
2e7c0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2e7d0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
2e7e0 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
2e7f0 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65  ion F for all te
2e800 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  xt comparison.**
2e810 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74            operat
2e820 69 6f 6e 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ions on [databas
2e830 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
2e840 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20 74  on text values t
2e850 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
2e860 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  use the collatin
2e870 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  g sequence name 
2e880 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 37  X..**.** {F16627
2e890 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2e8a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2e8b0 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f  6(B,X,E,P,F)] wo
2e8c0 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  rks the same.** 
2e8d0 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c           as [sql
2e8e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2e8f0 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
2e900 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
2e910 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
2e920 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69  llation name X i
2e930 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20  s understood as 
2e940 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
2e950 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
2e960 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64 20          instead 
2e970 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  of UTF-8..**.** 
2e980 7b 46 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75  {F16630} When mu
2e990 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f  ltiple compariso
2e9a0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  n functions are 
2e9b0 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68  available for th
2e9c0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
2e9d0 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71     collating seq
2e9e0 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68  uence, SQLite ch
2e9f0 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68  ooses the one wh
2ea00 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ose text encodin
2ea10 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  g.**          re
2ea20 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
2ea30 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65   amount of conve
2ea40 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64  rsion from the d
2ea50 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20  efault.**       
2ea60 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67     text encoding
2ea70 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2ea80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ea90 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2eaa0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
2eab0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2eac0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
2ead0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
2eae0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2eaf0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2eb00 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2eb10 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
2eb20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2eb30 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
2eb40 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2eb50 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2eb60 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2eb70 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
2eb80 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
2eb90 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
2eba0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
2ebb0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
2ebc0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
2ebd0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2ebe0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
2ebf0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2ec00 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
2ec10 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2ec20 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
2ec30 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2ec40 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2ec50 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2ec60 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2ec70 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
2ec80 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
2ec90 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a 2a 2a  s {F16700}.**.**
2eca0 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67   To avoid having
2ecb0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
2ecc0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2ecd0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
2ece0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
2ecf0 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
2ed00 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2ed10 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
2ed20 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
2ed30 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
2ed40 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  to be called whe
2ed50 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
2ed60 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2ed70 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 75  uence is.** requ
2ed80 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ired..**.** If t
2ed90 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
2eda0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2edb0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
2edc0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
2edd0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
2ede0 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
2edf0 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
2ee00 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2ee10 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
2ee20 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
2ee30 2d 38 2e 20 7b 46 31 36 37 30 33 7d 20 49 66 20  -8. {F16703} If 
2ee40 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2ee50 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
2ee60 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a  used, the names.
2ee70 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 61 73  ** are passed as
2ee80 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
2ee90 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
2eea0 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20  rder. A call to 
2eeb0 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69  either.** functi
2eec0 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20  on replaces any 
2eed0 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63  existing callbac
2eee0 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  k..**.** When th
2eef0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
2ef00 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
2ef10 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
2ef20 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
2ef30 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2ef40 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2ef50 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2ef60 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2ef70 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2ef80 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
2ef90 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2efa0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68  he database.** h
2efb0 61 6e 64 6c 65 2e 20 20 54 68 65 20 74 68 69 72  andle.  The thir
2efc0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
2efd0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
2efe0 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
2eff0 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
2f000 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
2f010 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
2f020 74 0a 2a 2a 20 64 65 73 69 72 61 62 6c 65 20 66  t.** desirable f
2f030 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
2f040 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 66 75  tion sequence fu
2f050 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
2f060 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
2f070 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2f080 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
2f090 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
2f0a0 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a  n sequence..**.*
2f0b0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
2f0c0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
2f0d0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
2f0e0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
2f0f0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2f100 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2f110 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
2f120 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2f130 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2f140 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2f150 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  tion_v2()]..**.*
2f160 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2f170 0a 2a 2a 20 7b 46 31 36 37 30 32 7d 20 41 20 73  .** {F16702} A s
2f180 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2f190 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
2f1a0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c  tion_needed(D,P,
2f1b0 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F)].**          
2f1c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  or [sqlite3_coll
2f1d0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44  ation_needed16(D
2f1e0 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a  ,P,F)] causes.**
2f1f0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64            the [d
2f200 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f210 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20  on] D to invoke 
2f220 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20  callback F with 
2f230 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
2f240 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68    parameter P wh
2f250 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73 20  enever it needs 
2f260 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  a comparison fun
2f270 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20  ction for a.**  
2f280 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
2f290 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74 20  g sequence that 
2f2a0 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77  it does not know
2f2b0 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46   about..**.** {F
2f2c0 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63 63  16704} Each succ
2f2d0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
2f2e0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2f2f0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a  n_needed()] or.*
2f300 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2f310 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2f320 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69  eded16()] overri
2f330 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  des the callback
2f340 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20   registered.**  
2f350 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73          on the s
2f360 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
2f370 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69  nnection] by pri
2f380 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68  or calls to eith
2f390 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  er.**          i
2f3a0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2f3b0 7b 46 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d  {F16706} The nam
2f3c0 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74  e of the request
2f3d0 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ed collating fun
2f3e0 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20  ction passed in 
2f3f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2f400 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2f410 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
2f420 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65   in UTF-8 if the
2f430 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
2f440 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73 74        was regist
2f450 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
2f460 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2f470 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20  eded()] and.**  
2f480 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55 54          is in UT
2f490 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2f4a0 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63 61   order if the ca
2f4b0 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20  llback was.**   
2f4c0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
2f4d0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2f4e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2f4f0 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 0a 2a  d16()]..**.** .*
2f500 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2f510 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
2f520 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2f530 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
2f540 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
2f550 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
2f560 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
2f570 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2f580 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
2f590 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2f5a0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
2f5b0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
2f5c0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
2f5d0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2f5e0 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
2f5f0 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
2f600 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
2f610 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
2f620 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
2f630 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
2f640 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
2f650 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
2f660 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
2f670 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
2f680 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
2f690 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
2f6a0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
2f6b0 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
2f6c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2f6d0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2f6e0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
2f6f0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
2f700 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
2f710 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
2f720 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
2f730 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
2f740 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
2f750 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
2f760 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
2f770 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
2f780 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
2f790 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
2f7a0 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
2f7b0 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
2f7c0 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
2f7d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
2f7e0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
2f7f0 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
2f800 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
2f810 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
2f820 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
2f830 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
2f840 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
2f850 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2f860 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2f870 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
2f880 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2f890 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
2f8a0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
2f8b0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
2f8c0 41 50 49 33 52 45 46 3a 20 20 53 75 73 70 65 6e  API3REF:  Suspen
2f8d0 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
2f8e0 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 46 31  A Short Time {F1
2f8f0 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0530}.**.** The 
2f900 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
2f910 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 75 73  function.** caus
2f920 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
2f930 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
2f940 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
2f950 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
2f960 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
2f970 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
2f980 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
2f990 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
2f9a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
2f9b0 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
2f9c0 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
2f9d0 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  th .** milliseco
2f9e0 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
2f9f0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
2fa00 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
2fa10 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20  d up to .** the 
2fa20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
2fa30 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
2fa40 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
2fa50 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a  eep actually .**
2fa60 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
2fa70 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2fa80 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
2fa90 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
2faa0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
2fab0 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
2fac0 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
2fad0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
2fae0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
2faf0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
2fb00 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2fb10 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 33 7d  :.**.** {F10533}
2fb20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
2fb30 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
2fb40 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
2fb50 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20  leep.**         
2fb60 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
2fb70 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
2fb80 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65  vfs|VFS] in orde
2fb90 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
2fba0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
2fbb0 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
2fbc0 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74 20  t thread for at 
2fbd0 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  least.**        
2fbe0 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73    M milliseconds
2fbf0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 36 7d  ..**.** {F10536}
2fc00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
2fc10 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
2fc20 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2fc30 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20  mber of.**      
2fc40 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73      milliseconds
2fc50 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
2fc60 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66 20  ly requested of 
2fc70 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a  the operating.**
2fc80 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65 6d            system
2fc90 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  , which might be
2fca0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
2fcb0 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f   parameter M..*/
2fcc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
2fcd0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
2fce0 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65 20  CAPI3REF:  Name 
2fcf0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
2fd00 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
2fd10 46 69 6c 65 73 20 7b 46 31 30 33 31 30 7d 0a 2a  Files {F10310}.*
2fd20 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f  *.** If this glo
2fd30 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
2fd40 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2fd50 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
2fd60 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
2fd70 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61  f a folder (a.ka
2fd80 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
2fd90 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
2fda0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
2fdb0 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c  d by SQLite will
2fdc0 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
2fdd0 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49  at directory.  I
2fde0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
2fdf0 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** is NULL point
2fe00 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
2fe10 64 6f 65 73 20 61 20 73 65 61 72 63 68 20 66 6f  does a search fo
2fe20 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
2fe30 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69   temporary.** fi
2fe40 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
2fe50 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
2fe60 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69  fe to modify thi
2fe70 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 20  s variable once 
2fe80 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
2fe90 63 74 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65 65  ction.** has bee
2fea0 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73  n opened.  It is
2feb0 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
2fec0 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
2fed0 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
2fee0 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
2fef0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
2ff00 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
2ff10 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
2ff20 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
2ff30 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d  een call and rem
2ff40 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68  ain unchanged th
2ff50 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c  ereafter..*/.SQL
2ff60 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
2ff70 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
2ff80 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
2ff90 43 41 50 49 33 52 45 46 3a 20 20 54 65 73 74 20  CAPI3REF:  Test 
2ffa0 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 44 61  To See If The Da
2ffb0 74 61 62 61 73 65 20 49 73 20 49 6e 20 41 75 74  tabase Is In Aut
2ffc0 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 46  o-Commit Mode {F
2ffd0 31 32 39 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12930}.**.** The
2ffe0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
2fff0 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66  ocommit() interf
30000 61 63 65 73 20 72 65 74 75 72 6e 73 20 6e 6f 6e  aces returns non
30010 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
30020 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
30030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30040 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
30050 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
30060 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
30070 6c 79 2e 20 20 20 41 75 74 6f 63 6f 6d 6d 69 74  ly.   Autocommit
30080 20 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62   mode is on.** b
30090 79 20 64 65 66 61 75 6c 74 2e 20 20 41 75 74 6f  y default.  Auto
300a0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
300b0 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
300c0 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
300d0 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  ** Autocommit mo
300e0 64 65 20 69 73 20 72 65 65 6e 61 62 6c 65 64 20  de is reenabled 
300f0 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
30100 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
30110 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
30120 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
30130 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
30140 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
30150 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
30160 72 61 6e 73 61 63 74 69 6f 6e 73 20 28 65 72 72  ransactions (err
30170 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53  ors including [S
30180 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51  QLITE_FULL], [SQ
30190 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a 2a  LITE_IOERR], .**
301a0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
301b0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
301c0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
301d0 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
301e0 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
301f0 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
30200 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
30210 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
30220 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
30230 20 69 66 20 53 51 4c 69 74 65 20 61 75 74 6f 6d   if SQLite autom
30240 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
30250 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
30260 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
30270 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
30280 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
30290 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
302a0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 31 7d  :.**.** {F12931}
302b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65   The [sqlite3_ge
302c0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d  t_autocommit(D)]
302d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
302e0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
302f0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
30300 69 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  if the [database
30310 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69   connection] D i
30320 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
30330 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20  utocommit.**    
30340 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70        mode, resp
30350 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
30360 7b 46 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d  {F12932} Autocom
30370 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
30380 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
30390 20 7b 46 31 32 39 33 33 7d 20 41 75 74 6f 63 6f   {F12933} Autoco
303a0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
303b0 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65  abled by a succe
303c0 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74  ssful [BEGIN] st
303d0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  atement..**.** {
303e0 46 31 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d  F12934} Autocomm
303f0 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  it mode is enabl
30400 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73 66  ed by a successf
30410 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b  ul [COMMIT] or [
30420 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20  ROLLBACK].**    
30430 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e        statement.
30440 0a 2a 2a 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  .** .**.** LIMIT
30450 41 54 49 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20 7b  ATIONS:.***.** {
30460 55 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 68  U12936} If anoth
30470 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65  er thread change
30480 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74  s the autocommit
30490 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64   status of the d
304a0 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20  atabase.**      
304b0 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77      connection w
304c0 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
304d0 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
304e0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
304f0 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lue.**          
30500 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
30510 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
30520 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69  _autocommit(sqli
30530 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
30540 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54 68  PI3REF:  Find Th
30550 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
30560 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
30570 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 31 32  Statement {F1312
30580 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
30590 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
305a0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
305b0 72 6e 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rns the [sqlite3
305c0 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  *] database hand
305d0 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a  le to which a.**
305e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
305f0 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a  ment] belongs..*
30600 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 68  * The database h
30610 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62  andle returned b
30620 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
30630 64 6c 65 0a 2a 2a 20 69 73 20 74 68 65 20 73 61  dle.** is the sa
30640 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  me database hand
30650 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74  le that was.** t
30660 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
30670 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
30680 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
30690 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a  or its variants.
306a0 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65 64  ** that was used
306b0 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 73   to create the s
306c0 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
306d0 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a  first place..**.
306e0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
306f0 2a 0a 2a 2a 20 7b 46 31 33 31 32 33 7d 20 54 68  *.** {F13123} Th
30700 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  e [sqlite3_db_ha
30710 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66 61  ndle(S)] interfa
30720 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
30730 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
30740 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
30750 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73  e connection] as
30760 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
30770 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
30780 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
30790 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
307a0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
307b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
307c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
307d0 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
307e0 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
307f0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  on Callbacks {F1
30800 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2950}.**.** The 
30810 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
30820 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
30830 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
30840 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
30850 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
30860 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
30870 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74  ction is committ
30880 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  ed..** Any callb
30890 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
308a0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
308b0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
308c0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
308d0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
308e0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
308f0 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71  idden..** The sq
30900 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
30910 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
30920 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
30930 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
30940 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
30950 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
30960 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74  ction is committ
30970 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  ed..** Any callb
30980 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
30990 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
309a0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
309b0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
309c0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
309d0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
309e0 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41  idden..** The pA
309f0 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
30a00 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a  assed through.**
30a10 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
30a20 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  .  If the callba
30a30 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
30a40 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a  ook function .**
30a50 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
30a60 6f 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  o, then the comm
30a70 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  it is converted 
30a80 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
30a90 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
30aa0 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70  r function was p
30ab0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
30ac0 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72  ered, its.** pAr
30ad0 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  g value is retur
30ae0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
30af0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
30b00 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
30b10 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74  ing a NULL funct
30b20 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65  ion disables the
30b30 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
30b40 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65   For the purpose
30b50 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
30b60 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
30b70 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
30b80 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  n .** rolled bac
30b90 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
30ba0 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
30bb0 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
30bc0 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
30bd0 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
30be0 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
30bf0 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
30c00 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c  ccur..** The rol
30c10 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
30c20 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
30c30 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
30c40 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
30c50 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
30c60 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
30c70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
30c80 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65  s closed..** The
30c90 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
30ca0 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
30cb0 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
30cc0 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20  on is.** rolled 
30cd0 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20 63  back because a c
30ce0 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72  ommit callback r
30cf0 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f  eturned non-zero
30d00 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63  ..** <todo> Chec
30d10 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f  k on this </todo
30d20 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  >.**.** These ar
30d30 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  e experimental i
30d40 6e 74 65 72 66 61 63 65 73 20 61 6e 64 20 61 72  nterfaces and ar
30d50 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  e subject to cha
30d60 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  nge..**.** INVAR
30d70 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
30d80 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2951} The [sqlit
30d90 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
30da0 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
30db0 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
30dc0 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
30dd0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack function F t
30de0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
30df0 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
30e00 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
30e10 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20    a transaction 
30e20 63 6f 6d 6d 69 74 73 20 6f 6e 20 5b 64 61 74 61  commits on [data
30e30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30e40 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35   D..**.** {F1295
30e50 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
30e60 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c  commit_hook(D,F,
30e70 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
30e80 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20  turns the P.**  
30e90 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74          argument
30ea0 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
30eb0 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65  us call with the
30ec0 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20   same .**       
30ed0 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
30ee0 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72  nection ] D , or
30ef0 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72   NULL on the fir
30f00 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  st call.**      
30f10 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 63      for a partic
30f20 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65 20 63  ular [database c
30f30 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
30f40 0a 2a 2a 20 7b 46 31 32 39 35 33 7d 20 45 61 63  .** {F12953} Eac
30f50 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
30f60 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
30f70 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  ] overwrites the
30f80 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
30f90 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
30fa0 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e   by prior calls.
30fb0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 7d 20  .**.** {F12954} 
30fc0 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e  If the F argumen
30fd0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
30fe0 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  mmit_hook(D,F,P)
30ff0 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20  ] is NULL.**    
31000 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 63        then the c
31010 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62  ommit hook callb
31020 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c 65 64  ack is cancelled
31030 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b   and no callback
31040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
31050 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74  invoked when a t
31060 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69  ransaction commi
31070 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35  ts..**.** {F1295
31080 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74  5} If the commit
31090 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
310a0 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20  s non-zero then 
310b0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a  the commit is.**
310c0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72            conver
310d0 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
310e0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ack..**.** {F129
310f0 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
31100 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
31110 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
31120 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
31130 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
31140 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack function F t
31150 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
31160 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
31170 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
31180 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20    a transaction 
31190 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 5b 64  rolls back on [d
311a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
311b0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
311c0 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2962} The [sqlit
311d0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
311e0 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
311f0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ce returns the P
31200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
31210 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
31220 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74  revious call wit
31230 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 20  h the same .**  
31240 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
31250 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20 44  e connection ] D
31260 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68   , or NULL on th
31270 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20  e first call.** 
31280 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 70           for a p
31290 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74 61 62  articular [datab
312a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
312b0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 33  D..**.** {F12963
312c0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
312d0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
312e0 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69  _hook()] overwri
312f0 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  tes the callback
31300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
31310 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72  istered by prior
31320 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   calls..**.** {F
31330 31 32 39 36 34 7d 20 49 66 20 74 68 65 20 46 20  12964} If the F 
31340 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
31350 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
31360 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55  ok(D,F,P)] is NU
31370 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
31380 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b  hen the rollback
31390 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
313a0 73 20 63 61 6e 63 65 6c 6c 65 64 20 61 6e 64 20  s cancelled and 
313b0 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  no callback.**  
313c0 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b          is invok
313d0 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61  ed when a transa
313e0 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b  ction rolls back
313f0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
31400 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
31410 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
31420 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
31430 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
31440 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
31450 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
31460 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
31470 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31480 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
31490 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
314a0 6b 73 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a  ks {F12970}.**.*
314b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70  * The sqlite3_up
314c0 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  date_hook() inte
314d0 72 66 61 63 65 0a 2a 2a 20 72 65 67 69 73 74 65  rface.** registe
314e0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
314f0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
31500 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31510 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62  ion identified b
31520 79 20 74 68 65 20 0a 2a 2a 20 66 69 72 73 74 20  y the .** first 
31530 61 72 67 75 6d 65 6e 74 20 74 6f 20 62 65 20 69  argument to be i
31540 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
31550 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  a row is updated
31560 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
31570 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  leted..** Any ca
31580 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
31590 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
315a0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 66   this function f
315b0 6f 72 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20  or the same .** 
315c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
315d0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
315e0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  n..**.** The sec
315f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
31600 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
31610 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
31620 6f 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20 72  oke when a .** r
31630 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
31640 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
31650 65 64 2e 20 0a 2a 2a 20 54 68 65 20 66 69 72 73  ed. .** The firs
31660 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
31670 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a  e callback is.**
31680 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
31690 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
316a0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
316b0 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73  hook()..** The s
316c0 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a  econd callback .
316d0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ** argument is o
316e0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
316f0 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
31700 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54  ELETE] or [SQLIT
31710 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 64 65  E_UPDATE],.** de
31720 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
31730 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
31740 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
31750 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  k to be invoked.
31760 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e  .** The third an
31770 64 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67  d .** fourth arg
31780 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
31790 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
317a0 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 64  ointers to the d
317b0 61 74 61 62 61 73 65 20 61 6e 64 20 0a 2a 2a 20  atabase and .** 
317c0 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61  table name conta
317d0 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74  ining the affect
317e0 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66  ed row..** The f
317f0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
31800 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20 74  rameter is .** t
31810 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
31820 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63  row..** In the c
31830 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65  ase of an update
31840 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f  , this is the ro
31850 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68  wid after .** th
31860 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70  e update takes p
31870 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lace..**.** The 
31880 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e  update hook is n
31890 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
318a0 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20  internal system 
318b0 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f  tables are.** mo
318c0 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c  dified (i.e. sql
318d0 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
318e0 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e  qlite_sequence).
318f0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
31900 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70  r function was p
31910 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
31920 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76  ered, its pArg v
31930 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72  alue.** is retur
31940 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
31950 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
31960 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
31970 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37  TS:.**.** {F1297
31980 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
31990 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
319a0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  P)] interface ca
319b0 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  uses callback.**
319c0 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
319d0 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
319e0 65 64 20 77 69 74 68 20 66 69 72 73 74 20 70 61  ed with first pa
319f0 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76  rameter P whenev
31a00 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  er.**          a
31a10 20 74 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f   table row is mo
31a20 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64  dified, inserted
31a30 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a  , or deleted on.
31a40 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
31a50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31a60 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ] D..**.** {F129
31a70 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  73} The [sqlite3
31a80 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
31a90 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
31aa0 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
31ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
31ac0 50 20 66 6f 72 20 74 68 65 20 70 72 65 76 69 6f  P for the previo
31ad0 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73  us call on the s
31ae0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
31af0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20  nnection] D,.** 
31b00 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
31b10 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 63   for the first c
31b20 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  all..**.** {F129
31b30 37 35 7d 20 49 66 20 74 68 65 20 75 70 64 61 74  75} If the updat
31b40 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  e hook callback 
31b50 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 75 70  F in [sqlite3_up
31b60 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  date_hook(D,F,P)
31b70 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
31b80 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 6e   NULL then the n
31b90 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63  o update callbac
31ba0 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a  ks are made..**.
31bb0 2a 2a 20 7b 46 31 32 39 37 37 7d 20 45 61 63 68  ** {F12977} Each
31bc0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
31bd0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
31be0 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 73 20  F,P)] overrides 
31bf0 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20 20  prior calls.**  
31c00 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 73          to the s
31c10 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  ame interface on
31c20 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
31c30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
31c40 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 39  D..**.** {F12979
31c50 7d 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  } The update hoo
31c60 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
31c70 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
31c80 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 0a 2a  nternal system.*
31c90 2a 20 20 20 20 20 20 20 20 20 20 74 61 62 6c 65  *          table
31ca0 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 74 65  s such as sqlite
31cb0 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
31cc0 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72 65 20  te_sequence are 
31cd0 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
31ce0 7b 46 31 32 39 38 31 7d 20 54 68 65 20 73 65 63  {F12981} The sec
31cf0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
31d00 20 74 68 65 20 75 70 64 61 74 65 20 63 61 6c 6c   the update call
31d10 62 61 63 6b 20 0a 2a 2a 20 20 20 20 20 20 20 20  back .**        
31d20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c    is one of [SQL
31d30 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
31d40 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20  LITE_DELETE] or 
31d50 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
31d60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 70  .**          dep
31d70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
31d80 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
31d90 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
31da0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
31db0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 33 7d 20 54  **.** {F12983} T
31dc0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
31dd0 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
31de0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
31df0 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a 2a  ntain pointers.*
31e00 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a 65  *          to ze
31e10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
31e20 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69 63  F-8 strings whic
31e30 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73 20  h are the names 
31e40 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
31e50 20 20 20 64 61 74 61 62 61 73 65 20 61 6e 64 20     database and 
31e60 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 62 65  table that is be
31e70 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a 2a  ing updated...**
31e80 20 7b 46 31 32 39 38 35 7d 20 54 68 65 20 66 69   {F12985} The fi
31e90 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72  nal callback par
31ea0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 6f  ameter is the ro
31eb0 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20 61  wid of the row a
31ec0 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  fter.**         
31ed0 20 74 68 65 20 63 68 61 6e 67 65 20 6f 63 63 75   the change occu
31ee0 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  rs..*/.void *sql
31ef0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
31f00 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
31f10 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
31f20 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
31f30 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
31f40 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
31f50 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
31f60 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62   CAPI3REF:  Enab
31f70 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68  le Or Disable Sh
31f80 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65  ared Pager Cache
31f90 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F10330}.**.** 
31fa0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
31fb0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
31fc0 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20   the sharing of 
31fd0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63  the database cac
31fe0 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61  he.** and schema
31ff0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
32000 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74   between connect
32010 69 6f 6e 73 20 74 6f 20 74 68 65 20 73 61 6d 65  ions to the same
32020 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 53 68   database..** Sh
32030 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
32040 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
32050 20 69 73 20 74 72 75 65 20 61 6e 64 20 64 69 73   is true and dis
32060 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67  abled if the arg
32070 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61 6c 73  ument.** is fals
32080 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73  e..**.** Cache s
32090 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
320a0 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 0a 2a  d and disabled.*
320b0 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20  * for an entire 
320c0 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 20 54  process. {END} T
320d0 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20  his is a change 
320e0 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  as of SQLite ver
320f0 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a 20 49  sion 3.5.0..** I
32100 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
32110 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61 72   of SQLite, shar
32120 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c  ing was.** enabl
32130 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
32140 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
32150 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
32160 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69   The cache shari
32170 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74  ng mode set by t
32180 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66  his interface ef
32190 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71  fects all subseq
321a0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
321b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
321c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
321d0 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  _v2()], and [sql
321e0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
321f0 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61  ** Existing data
32200 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
32210 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68   continue use th
32220 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a  e sharing mode.*
32230 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66  * that was in ef
32240 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65  fect at the time
32250 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65   they were opene
32260 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  d..**.** Virtual
32270 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62   tables cannot b
32280 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 68  e used with a sh
32290 61 72 65 64 20 63 61 63 68 65 2e 20 20 20 57 68  ared cache.   Wh
322a0 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  en shared.** cac
322b0 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74  he is enabled, t
322c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
322d0 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49  te_module()] API
322e0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
322f0 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  r.** virtual tab
32300 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  les will always 
32310 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
32320 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
32330 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
32340 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
32350 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a 20 65  d cache was.** e
32360 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
32370 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ed successfully.
32380 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
32390 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
323a0 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
323b0 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69  * Shared cache i
323c0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
323d0 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20  fault. But this 
323e0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a  might change in.
323f0 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ** future releas
32400 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  es of SQLite.  A
32410 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
32420 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72   care about shar
32430 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74  ed.** cache sett
32440 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69  ing should set i
32450 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a  t explicitly..**
32460 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
32470 2a 2a 20 0a 2a 2a 20 7b 46 31 30 33 33 31 7d 20  ** .** {F10331} 
32480 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
32490 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
324a0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
324b0 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20 20  d_cache(B)].**  
324c0 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e 61          will ena
324d0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 73  ble or disable s
324e0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
324f0 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71 75   for any subsequ
32500 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ently.**        
32510 20 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62    created [datab
32520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32530 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
32540 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33  ess..**.** {F103
32550 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64 20  36} When shared 
32560 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
32570 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
32580 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a  reate_module()].
32590 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
325a0 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61 79  rface will alway
325b0 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  s return an erro
325c0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 37  r..**.** {F10337
325d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
325e0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
325f0 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63 65  he(B)] interface
32600 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
32610 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
32620 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
32630 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
32640 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73  disabled success
32650 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fully..**.** {F1
32660 30 33 33 39 7d 20 53 68 61 72 65 64 20 63 61 63  0339} Shared cac
32670 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  he is disabled b
32680 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e  y default..*/.in
32690 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
326a0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e  _shared_cache(in
326b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
326c0 52 45 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f  REF:  Attempt To
326d0 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72   Free Heap Memor
326e0 79 20 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a 2a  y {F17340}.**.**
326f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c   The sqlite3_rel
32700 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
32710 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
32720 20 74 6f 0a 2a 2a 20 66 72 65 65 20 4e 20 62 79   to.** free N by
32730 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  tes of heap memo
32740 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
32750 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
32760 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
32770 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74  ations held by t
32780 68 65 20 64 61 74 61 62 61 73 65 20 6c 61 62 72  he database labr
32790 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f  ary. {END}  Memo
327a0 72 79 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 61  ry used.** to ca
327b0 63 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  che database pag
327c0 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65  es to improve pe
327d0 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20  rformance is an 
327e0 65 78 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6f  example of.** no
327f0 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
32800 72 79 2e 20 20 53 71 6c 69 74 65 33 5f 72 65 6c  ry.  Sqlite3_rel
32810 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65  ease_memory() re
32820 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
32830 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74  ber of bytes act
32840 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69  ually freed, whi
32850 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65  ch might be more
32860 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e   or less.** than
32870 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75   the amount requ
32880 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ested..**.** INV
32890 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
328a0 46 31 37 33 34 31 7d 20 54 68 65 20 5b 73 71 6c  F17341} The [sql
328b0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
328c0 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  ory(N)] interfac
328d0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a  e attempts to.**
328e0 20 20 20 20 20 20 20 20 20 20 66 72 65 65 20 4e            free N
328f0 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d   bytes of heap m
32900 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
32910 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
32920 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ial.**          
32930 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
32940 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ns held by the d
32950 61 74 61 62 61 73 65 20 6c 61 62 72 61 72 79 2e  atabase labrary.
32960 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 34 32 7d 20  .**.** {F16342} 
32970 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  The [sqlite3_rel
32980 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20  ease_memory(N)] 
32990 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
329a0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  er.**          o
329b0 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
329c0 20 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69   freed, which mi
329d0 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
329e0 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ess.**          
329f0 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  than the amount 
32a00 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e  requested..*/.in
32a10 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  t sqlite3_releas
32a20 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a  e_memory(int);..
32a30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32a40 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20   Impose A Limit 
32a50 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 46 31  On Heap Size {F1
32a60 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7350}.**.** The 
32a70 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
32a80 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66  p_limit() interf
32a90 61 63 65 0a 2a 2a 20 70 6c 61 63 65 73 20 61 20  ace.** places a 
32aa0 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20  "soft" limit on 
32ab0 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65  the amount of he
32ac0 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d  ap memory that m
32ad0 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a  ay be allocated.
32ae0 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 49 66  ** by SQLite. If
32af0 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c   an internal all
32b00 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  ocation is reque
32b10 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 77 6f  sted .** that wo
32b20 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 20 73  uld exceed the s
32b30 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20  oft heap limit, 
32b40 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
32b50 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a 2a  _memory()] is.**
32b60 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 20   invoked one or 
32b70 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72  more times to fr
32b80 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65  ee up some space
32b90 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f   before the allo
32ba0 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61 64  cation.** is mad
32bb0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d  e..**.** The lim
32bc0 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f  it is called "so
32bd0 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 0a  ft", because if.
32be0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** [sqlite3_rele
32bf0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61  ase_memory()] ca
32c00 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66  nnot.** free suf
32c10 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
32c20 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
32c30 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
32c40 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
32c50 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
32c60 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
32c70 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
32c80 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
32c90 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  *.** A negative 
32ca0 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
32cb0 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74  r N means that t
32cc0 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20  here is no soft 
32cd0 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a  heap limit and.*
32ce0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
32cf0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
32d00 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  l only be called
32d10 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
32d20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68  exhausted..** Th
32d30 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
32d40 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
32d50 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
32d60 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  .**.** SQLite ma
32d70 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72  kes a best effor
32d80 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73  t to honor the s
32d90 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20  oft heap limit. 
32da0 20 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20   .** But if the 
32db0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
32dc0 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72 65 64 2c 20  cannot honored, 
32dd0 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
32de0 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
32df0 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
32e00 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20  fication.  This 
32e10 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74  is why the limit
32e20 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 61   is .** called a
32e30 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20   "soft" limit.  
32e40 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  It is advisory o
32e50 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  nly..**.** Prior
32e60 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
32e70 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72  on 3.5.0, this r
32e80 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73  outine only cons
32e90 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f  trained the memo
32ea0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ry.** allocated 
32eb0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
32ec0 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68  ad - the same th
32ed0 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68  read in which th
32ee0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75  is routine.** ru
32ef0 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ns.  Beginning w
32f00 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69  ith SQLite versi
32f10 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f  on 3.5.0, the so
32f20 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
32f30 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61  .** applied to a
32f40 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20  ll threads. The 
32f50 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20  value specified 
32f60 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
32f70 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e  p limit.** is an
32f80 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20   upper bound on 
32f90 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79  the total memory
32fa0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
32fb0 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a  all threads. In.
32fc0 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  ** version 3.5.0
32fd0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63   there is no mec
32fe0 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74  hanism for limit
32ff0 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61  ing the heap usa
33000 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69  ge for.** indivi
33010 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a  dual threads..**
33020 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
33030 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 31 7d 20 54  **.** {F16351} T
33040 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  he [sqlite3_soft
33050 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20  _heap_limit(N)] 
33060 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 73  interface places
33070 20 61 20 73 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a   a soft limit.**
33080 20 20 20 20 20 20 20 20 20 20 6f 66 20 4e 20 62            of N b
33090 79 74 65 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75  ytes on the amou
330a0 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
330b0 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
330c0 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  located.**      
330d0 20 20 20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74      using [sqlit
330e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
330f0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
33100 28 29 5d 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  ()] at any point
33110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
33120 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  time..**.** {F16
33130 33 35 32 7d 20 49 66 20 61 20 63 61 6c 6c 20 74  352} If a call t
33140 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
33150 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
33160 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c  _realloc()] woul
33170 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  d.**          ca
33180 75 73 65 20 74 68 65 20 74 6f 74 61 6c 20 61 6d  use the total am
33190 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65  ount of allocate
331a0 64 20 6d 65 6d 6f 72 79 20 74 6f 20 65 78 63 65  d memory to exce
331b0 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ed the.**       
331c0 20 20 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d     soft heap lim
331d0 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  it, then [sqlite
331e0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
331f0 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  ()] is invoked.*
33200 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 6e  *          in an
33210 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75   attempt to redu
33220 63 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 75 73  ce the memory us
33230 61 67 65 20 70 72 69 6f 72 20 74 6f 20 70 72 6f  age prior to pro
33240 63 65 65 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ceeding.**      
33250 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 65 6d      with the mem
33260 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ory allocation a
33270 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ttempt..**.** {F
33280 31 36 33 35 33 7d 20 43 61 6c 6c 73 20 74 6f 20  16353} Calls to 
33290 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
332a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
332b0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 74  ealloc()] that t
332c0 72 69 67 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  rigger.**       
332d0 20 20 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72     attempts to r
332e0 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73 61  educe memory usa
332f0 67 65 20 74 68 72 6f 75 67 68 20 74 68 65 20 73  ge through the s
33300 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a  oft heap limit.*
33310 2a 20 20 20 20 20 20 20 20 20 20 6d 65 63 68 61  *          mecha
33320 6e 69 73 6d 20 63 6f 6e 74 69 6e 75 65 20 65 76  nism continue ev
33330 65 6e 20 69 66 20 74 68 65 20 61 74 74 65 6d 70  en if the attemp
33340 74 20 74 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f  t to reduce memo
33350 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75  ry.**          u
33360 73 61 67 65 20 69 73 20 75 6e 73 75 63 63 65 73  sage is unsucces
33370 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  sful..**.** {F16
33380 33 35 34 7d 20 41 20 6e 65 67 61 74 69 76 65 20  354} A negative 
33390 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
333a0 72 20 4e 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f  r N in a call to
333b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
333c0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
333d0 6c 69 6d 69 74 28 4e 29 5d 20 6d 65 61 6e 73 20  limit(N)] means 
333e0 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f  that there is no
333f0 20 73 6f 66 74 0a 2a 2a 20 20 20 20 20 20 20 20   soft.**        
33400 20 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64    heap limit and
33410 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
33420 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
33430 20 6f 6e 6c 79 20 62 65 0a 2a 2a 20 20 20 20 20   only be.**     
33440 20 20 20 20 20 63 61 6c 6c 65 64 20 77 68 65 6e       called when
33450 20 6d 65 6d 6f 72 79 20 69 73 20 63 6f 6d 70 6c   memory is compl
33460 65 74 65 6c 79 20 65 78 68 61 75 73 74 65 64 2e  etely exhausted.
33470 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 35 7d 20  .**.** {F16355} 
33480 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
33490 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
334a0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
334b0 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 38  o..**.** {F16358
334c0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
334d0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
334e0 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f 76 65 72  p_limit(N)] over
334f0 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  rides the.**    
33500 20 20 20 20 20 20 76 61 6c 75 65 73 20 73 65 74        values set
33510 20 62 79 20 61 6c 6c 20 70 72 69 6f 72 20 63 61   by all prior ca
33520 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  lls..*/.void sql
33530 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
33540 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  imit(int);../*.*
33550 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 78 74  * CAPI3REF:  Ext
33560 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62  ract Metadata Ab
33570 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20  out A Column Of 
33580 41 20 54 61 62 6c 65 20 7b 46 31 32 38 35 30 7d  A Table {F12850}
33590 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
335a0 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6d  ine.** returns m
335b0 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74 20 61  eta-data about a
335c0 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
335d0 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 20 64   of a specific d
335e0 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65  atabase.** table
335f0 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
33600 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  g the connection
33610 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64 20 61   handle passed a
33620 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63  s the first func
33630 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 6e  tion .** argumen
33640 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c  t..**.** The col
33650 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65  umn is identifie
33660 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c  d by the second,
33670 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
33680 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
33690 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
336a0 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  n. The second pa
336b0 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65  rameter is eithe
336c0 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  r the name of th
336d0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69  e database.** (i
336e0 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  .e. "main", "tem
336f0 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65  p" or an attache
33700 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74  d database) cont
33710 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69  aining the speci
33720 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72  fied.** table or
33730 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20   NULL. If it is 
33740 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61  NULL, then all a
33750 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
33760 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a  s are searched.*
33770 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20  * for the table 
33780 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
33790 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68 65 20  lgorithm as the 
337a0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
337b0 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73 6f  uses to .** reso
337c0 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20  lve unqualified 
337d0 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73  table references
337e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
337f0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
33800 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
33810 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65  function are the
33820 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
33830 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  n .** name of th
33840 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e  e desired column
33850 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
33860 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65  Neither of these
33870 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20   parameters .** 
33880 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
33890 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61 74  ** Meta informat
338a0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 20  ion is returned 
338b0 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68  by writing to th
338c0 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f  e memory locatio
338d0 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20  ns passed as.** 
338e0 74 68 65 20 35 74 68 20 61 6e 64 20 73 75 62 73  the 5th and subs
338f0 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72  equent parameter
33900 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
33910 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 65  on. Any of these
33920 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6d   .** arguments m
33930 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77  ay be NULL, in w
33940 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f  hich case the co
33950 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d  rresponding elem
33960 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a 20  ent of meta .** 
33970 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6f  information is o
33980 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  mmitted..**.** <
33990 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74 65  pre>.** Paramete
339a0 72 20 20 20 20 20 4f 75 74 70 75 74 20 54 79 70  r     Output Typ
339b0 65 20 20 20 20 20 20 44 65 73 63 72 69 70 74 69  e      Descripti
339c0 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  on.** ----------
339d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
339e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20  ---------.**.** 
339f0 20 20 35 74 68 20 20 20 20 20 20 20 20 20 63 6f    5th         co
33a00 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20 44  nst char*      D
33a10 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 36 74  ata type.**   6t
33a20 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20  h         const 
33a30 63 68 61 72 2a 20 20 20 20 20 20 4e 61 6d 65 20  char*      Name 
33a40 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 63  of the default c
33a50 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
33a60 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 20 20  e .**   7th     
33a70 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
33a80 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
33a90 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
33aa0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
33ab0 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 20 20  t.**   8th      
33ac0 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20     int          
33ad0 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20      True if the 
33ae0 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
33af0 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
33b00 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 20 20  Y.**   9th      
33b10 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20     int          
33b20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20      True if the 
33b30 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49 4e  column is AUTOIN
33b40 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65  CREMENT.** </pre
33b50 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  >.**.**.** The m
33b60 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f  emory pointed to
33b70 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65   by the characte
33b80 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  r pointers retur
33b90 6e 65 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20  ned for the .** 
33ba0 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65  declaration type
33bb0 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   and collation s
33bc0 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64  equence is valid
33bd0 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20   only until the 
33be0 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f  next .** call to
33bf0 20 61 6e 79 20 73 71 6c 69 74 65 20 41 50 49 20   any sqlite API 
33c00 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
33c10 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
33c20 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c   table is actual
33c30 6c 79 20 61 20 76 69 65 77 2c 20 74 68 65 6e 20  ly a view, then 
33c40 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
33c50 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  rned..**.** If t
33c60 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c  he specified col
33c70 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20  umn is "rowid", 
33c80 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64  "oid" or "_rowid
33c90 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e  _" and an .** IN
33ca0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
33cb0 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65  Y column has bee
33cc0 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  n explicitly dec
33cd0 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20  lared, then the 
33ce0 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 61 6d  output .** param
33cf0 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f  eters are set fo
33d00 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79  r the explicitly
33d10 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
33d20 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f  . If there is no
33d30 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64  .** explicitly d
33d40 65 63 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c 75  eclared IPK colu
33d50 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  mn, then the out
33d60 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20 61  put parameters a
33d70 72 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 66 6f  re set as .** fo
33d80 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  llows:.**.** <pr
33d90 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74  e>.**     data t
33da0 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a  ype: "INTEGER".*
33db0 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20  *     collation 
33dc0 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52  sequence: "BINAR
33dd0 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75  Y".**     not nu
33de0 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69  ll: 0.**     pri
33df0 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20  mary key: 1.**  
33e00 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e     auto incremen
33e10 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a  t: 0.** </pre>.*
33e20 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
33e30 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20  on may load one 
33e40 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20  or more schemas 
33e50 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69  from database fi
33e60 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72  les. If an.** er
33e70 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
33e80 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20  g this process, 
33e90 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73  or if the reques
33ea0 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c  ted table or col
33eb0 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  umn.** cannot be
33ec0 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49 54   found, an SQLIT
33ed0 45 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  E error code is 
33ee0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20  returned and an 
33ef0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
33f00 20 6c 65 66 74 20 69 6e 20 74 68 65 20 64 61 74   left in the dat
33f10 61 62 61 73 65 20 68 61 6e 64 6c 65 20 28 74 6f  abase handle (to
33f20 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73   be retrieved us
33f30 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  ing sqlite3_errm
33f40 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  sg())..**.** Thi
33f50 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76  s API is only av
33f60 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
33f70 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
33f80 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
33f90 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
33fa0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72  LUMN_METADATA pr
33fb0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
33fc0 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  l defined..*/.in
33fd0 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f  t sqlite3_table_
33fe0 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28  column_metadata(
33ff0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
34000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
34010 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  * Connection han
34020 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
34030 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
34040 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
34050 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f   name or NULL */
34060 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34070 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f  TableName,     /
34080 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a  * Table name */.
34090 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
340a0 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a  olumnName,    /*
340b0 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a   Column name */.
340c0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
340d0 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a  zDataType,    /*
340e0 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65   OUTPUT: Declare
340f0 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20  d data type */. 
34100 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
34110 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20  CollSeq,     /* 
34120 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f  OUTPUT: Collatio
34130 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  n sequence name 
34140 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75  */.  int *pNotNu
34150 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ll,             
34160 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
34170 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e   if NOT NULL con
34180 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a  straint exists *
34190 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72  /.  int *pPrimar
341a0 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20  yKey,           
341b0 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
341c0 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f  if column part o
341d0 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  f PK */.  int *p
341e0 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20  Autoinc         
341f0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
34200 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
34210 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e  is auto-incremen
34220 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
34230 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e  API3REF: Load An
34240 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36   Extension {F126
34250 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30  00}.**.** {F1260
34260 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  1} The sqlite3_l
34270 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
34280 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61 74 74  interface.** att
34290 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e  empts to load an
342a0 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
342b0 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  n library contai
342c0 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a  ned in the file.
342d0 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32 36 30  ** zFile. {F1260
342e0 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69  2} The entry poi
342f0 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b 46 31  nt is zProc. {F1
34300 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20  2603} zProc may 
34310 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69 63 68  be 0.** in which
34320 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f   case the name o
34330 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
34340 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20 74 6f  t defaults.** to
34350 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
34360 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a  ion_init"..**.**
34370 20 7b 46 31 32 36 30 34 7d 20 54 68 65 20 73 71   {F12604} The sq
34380 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
34390 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
343a0 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   shall.** return
343b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
343c0 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
343d0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
343e0 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
343f0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30  ng..**.** {F1260
34400 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f  5}.** If an erro
34410 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45  r occurs and pzE
34420 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20  rrMsg is not 0, 
34430 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73 71 6c 69  then the.** sqli
34440 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
34450 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  on() interface s
34460 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 20  hall attempt to 
34470 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77  fill *pzErrMsg w
34480 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d 65  ith .** error me
34490 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65  ssage text store
344a0 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
344b0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
344c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
344d0 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c   {END}  The call
344e0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ing function sho
344f0 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
34500 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69  mory.** by calli
34510 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
34520 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  ()]..**.** {F126
34530 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e  06}.** Extension
34540 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65   loading must be
34550 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
34560 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
34570 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
34580 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
34590 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f 72  ling this API or
345a0 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62   an error will b
345b0 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69  e returned..*/.i
345c0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  nt sqlite3_load_
345d0 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c  extension(.  sql
345e0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
345f0 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65     /* Load the e
34600 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68  xtension into th
34610 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  is database conn
34620 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ection */.  cons
34630 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20  t char *zFile,  
34640 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
34650 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20   shared library 
34660 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e  containing exten
34670 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  sion */.  const 
34680 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20  char *zProc,    
34690 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20  /* Entry point. 
346a0 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46   Derived from zF
346b0 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68  ile if 0 */.  ch
346c0 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20  ar **pzErrMsg   
346d0 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72      /* Put error
346e0 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66   message here if
346f0 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a   not 0 */.);../*
34700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
34710 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
34720 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
34730 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a 2a 0a 2a  ng {F12620}.**.*
34740 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f  * So as not to o
34750 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c  pen security hol
34760 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c  es in older appl
34770 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72  ications that ar
34780 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20  e.** unprepared 
34790 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74  to deal with ext
347a0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20  ension loading, 
347b0 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f  and as a means o
347c0 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65  f disabling.** e
347d0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
347e0 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
347f0 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  g user-entered S
34800 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  QL, the followin
34810 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 72 6f 76  g.** API is prov
34820 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65  ided to turn the
34830 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
34840 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68  xtension()] mech
34850 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20  anism on and.** 
34860 6f 66 66 2e 20 20 7b 46 31 32 36 32 32 7d 20 49  off.  {F12622} I
34870 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  t is off by defa
34880 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65 65 20 74  ult. {END} See t
34890 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a  icket #1863..**.
348a0 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43 61 6c 6c  ** {F12621} Call
348b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61   the sqlite3_ena
348c0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
348d0 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  on() routine.** 
348e0 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f  with onoff==1 to
348f0 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
34900 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e  loading on.** an
34910 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
34920 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20  noff==0 to turn 
34930 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
34940 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20  n. {END}.*/.int 
34950 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
34960 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71  oad_extension(sq
34970 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f  lite3 *db, int o
34980 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
34990 50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41 72 72  PI3REF: Make Arr
349a0 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41 75 74  angements To Aut
349b0 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20  omatically Load 
349c0 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31  An Extension {F1
349d0 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  2640}.**.** {F12
349e0 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69  641} This functi
349f0 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 73 20  on.** registers 
34a00 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74  an extension ent
34a10 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73  ry point that is
34a20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
34a30 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76  nvoked.** whenev
34a40 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  er a new databas
34a50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
34a60 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  opened using.** 
34a70 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34a80 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34a90 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  6()], or [sqlite
34aa0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 7b 45  3_open_v2()]. {E
34ab0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  ND}.**.** This A
34ac0 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65  PI can be invoke
34ad0 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61  d at program sta
34ae0 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f  rtup in order to
34af0 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65   register.** one
34b00 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61   or more statica
34b10 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e  lly linked exten
34b20 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20  sions that will 
34b30 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  be available.** 
34b40 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62  to all new datab
34b50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ase connections.
34b60 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 32 7d 20  .**.** {F12642} 
34b70 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73  Duplicate extens
34b80 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65  ions are detecte
34b90 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  d so calling thi
34ba0 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69 70  s routine multip
34bb0 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
34bc0 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73   the same extens
34bd0 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  ion is harmless.
34be0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 33 7d 20  .**.** {F12643} 
34bf0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  This routine sto
34c00 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  res a pointer to
34c10 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
34c20 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74 68  n an array.** th
34c30 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66  at is obtained f
34c40 72 6f 6d 20 73 71 6c 69 74 65 5f 6d 61 6c 6c 6f  rom sqlite_mallo
34c50 63 28 29 2e 20 7b 45 4e 44 7d 20 49 66 20 79 6f  c(). {END} If yo
34c60 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c  u run a memory l
34c70 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f  eak.** checker o
34c80 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61  n your program a
34c90 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20  nd it reports a 
34ca0 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20  leak because of 
34cb0 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74  this.** array, t
34cc0 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  hen invoke [sqli
34cd0 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
34ce0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f  xtension()] prio
34cf0 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77 6e  r.** to shutdown
34d00 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65 6d   to free the mem
34d10 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  ory..**.** {F126
34d20 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78  44} Automatic ex
34d30 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
34d40 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
34d50 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  s. {END}.**.** T
34d60 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
34d70 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
34d80 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
34d90 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d  change or.** rem
34da0 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72  oval in future r
34db0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
34dc0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
34dd0 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
34de0 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f 69  (void *xEntryPoi
34df0 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  nt);.../*.** CAP
34e00 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74  I3REF: Reset Aut
34e10 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e  omatic Extension
34e20 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 36 30   Loading {F12660
34e30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 31 7d  }.**.** {F12661}
34e40 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64   This function d
34e50 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76  isables all prev
34e60 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
34e70 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 65  d.** automatic e
34e80 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d  xtensions. {END}
34e90 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e    This.** routin
34ea0 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
34eb0 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72  ect of all prior
34ec0 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65   [sqlite3_auto_e
34ed0 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63  xtension()].** c
34ee0 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  alls..**.** {F12
34ef0 36 36 32 7d 20 54 68 69 73 20 63 61 6c 6c 20 64  662} This call d
34f00 69 73 61 62 6c 65 64 20 61 75 74 6f 6d 61 74 69  isabled automati
34f10 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20  c extensions in 
34f20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e  all threads. {EN
34f30 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  D}.**.** This in
34f40 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
34f50 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
34f60 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
34f70 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69   or.** removal i
34f80 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
34f90 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
34fa0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34fb0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
34fc0 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  n(void);.../*.**
34fd0 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
34fe0 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
34ff0 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
35000 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
35010 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ***.**.** The in
35020 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
35030 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
35040 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e  hanism is curren
35050 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
35060 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
35070 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
35080 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
35090 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
350a0 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
350b0 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
350c0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
350d0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
350e0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
350f0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
35100 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
35110 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73  hanism stablizes
35120 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
35130 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
35140 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
35150 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
35160 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
35170 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
35180 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
35190 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
351a0 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
351b0 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
351c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
351d0 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
351e0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
351f0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
35200 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
35210 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
35220 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
35230 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
35240 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
35250 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
35260 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
35270 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
35280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
35290 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a  irtual Table Obj
352a0 65 63 74 20 7b 46 31 38 30 30 30 7d 0a 2a 2a 20  ect {F18000}.** 
352b0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
352c0 33 5f 6d 6f 64 75 6c 65 0a 2a 2a 0a 2a 2a 20 41  3_module.**.** A
352d0 20 6d 6f 64 75 6c 65 20 69 73 20 61 20 63 6c 61   module is a cla
352e0 73 73 20 6f 66 20 76 69 72 74 75 61 6c 20 74 61  ss of virtual ta
352f0 62 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 75  bles.  Each modu
35300 6c 65 20 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a  le is defined.**
35310 20 62 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   by an instance 
35320 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
35330 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 69   structure.  Thi
35340 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73  s structure cons
35350 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f  ists.** mostly o
35360 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  f methods for th
35370 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72  e module..*/.str
35380 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
35390 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  le {.  int iVers
353a0 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72  ion;.  int (*xCr
353b0 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20  eate)(sqlite3*, 
353c0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
353d0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
353e0 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
353f0 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
35400 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
35410 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
35420 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
35430 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71  t (*xConnect)(sq
35440 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
35450 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
35460 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
35470 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
35480 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
35490 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
354a0 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
354b0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73  *);.  int (*xBes
354c0 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f  tIndex)(sqlite3_
354d0 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
354e0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a  ite3_index_info*
354f0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63  );.  int (*xDisc
35500 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f  onnect)(sqlite3_
35510 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
35520 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28  int (*xDestroy)(
35530 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
35540 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f  Tab);.  int (*xO
35550 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  pen)(sqlite3_vta
35560 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
35570 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a  3_vtab_cursor **
35580 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74  ppCursor);.  int
35590 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
355a0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
355b0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65  ;.  int (*xFilte
355c0 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  r)(sqlite3_vtab_
355d0 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78  cursor*, int idx
355e0 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Num, const char 
355f0 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20  *idxStr,.       
35600 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
35610 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  c, sqlite3_value
35620 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20   **argv);.  int 
35630 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33  (*xNext)(sqlite3
35640 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
35650 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71    int (*xEof)(sq
35660 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
35670 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  r*);.  int (*xCo
35680 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  lumn)(sqlite3_vt
35690 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
356a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
356b0 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77  t);.  int (*xRow
356c0 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  id)(sqlite3_vtab
356d0 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
356e0 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29  3_int64 *pRowid)
356f0 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74  ;.  int (*xUpdat
35700 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
35710 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
35720 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65  value **, sqlite
35730 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e  3_int64 *);.  in
35740 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69  t (*xBegin)(sqli
35750 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
35760 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
35770 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
35780 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
35790 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f  Commit)(sqlite3_
357a0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
357b0 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29  int (*xRollback)
357c0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
357d0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
357e0 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71  FindFunction)(sq
357f0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
35800 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e  b, int nArg, con
35810 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a  st char *zName,.
35820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35830 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70         void (**p
35840 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
35850 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
35860 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
35870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35880 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72       void **ppAr
35890 67 29 3b 0a 0a 20 20 69 6e 74 20 28 2a 78 52 65  g);..  int (*xRe
358a0 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74  name)(sqlite3_vt
358b0 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74  ab *pVtab, const
358c0 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b   char *zNew);.};
358d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
358e0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
358f0 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61  Indexing Informa
35900 74 69 6f 6e 20 7b 46 31 38 31 30 30 7d 0a 2a 2a  tion {F18100}.**
35910 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
35920 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a  e3_index_info.**
35930 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
35940 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
35950 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62  ture and its sub
35960 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73  structures is us
35970 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e  ed to.** pass in
35980 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61  formation into a
35990 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72  nd receive the r
359a0 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42  eply from the xB
359b0 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68  estIndex.** meth
359c0 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  od of an sqlite3
359d0 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69  _module.  The fi
359e0 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70  elds under **Inp
359f0 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a  uts** are the.**
35a00 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74   inputs to xBest
35a10 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65  Index and are re
35a20 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49  ad-only.  xBestI
35a30 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73  ndex inserts its
35a40 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
35a50 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a   the **Outputs**
35a60 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54   fields..**.** T
35a70 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
35a80 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57   array records W
35a90 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
35aa0 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 0a 2a  traints of the.*
35ab0 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20  * form:.**.**   
35ac0 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20        column OP 
35ad0 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65  expr.**.** Where
35ae0 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20   OP is =, &lt;, 
35af0 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20  &lt;=, &gt;, or 
35b00 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20 54 68 65 20  &gt;=.  .** The 
35b10 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61  particular opera
35b20 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  tor is stored.**
35b30 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b   in aConstraint[
35b40 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78  ].op.  The index
35b50 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
35b60 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a 20  s stored in .** 
35b70 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
35b80 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61  olumn.  aConstra
35b90 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
35ba0 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
35bb0 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
35bc0 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
35bd0 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
35be0 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
35bf0 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
35c00 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
35c10 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a  it cannot..**.**
35c20 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61   The optimizer a
35c30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
35c40 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68  erts terms of th
35c50 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20  e form "expr OP 
35c60 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d  column".** and m
35c70 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c  akes other simpl
35c80 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68  ifications to th
35c90 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69  e WHERE clause i
35ca0 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a  n an attempt to.
35cb0 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57  ** get as many W
35cc0 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
35cd0 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20  s into the form 
35ce0 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70  shown above as p
35cf0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20  ossible..** The 
35d00 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
35d10 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
35d20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
35d30 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65  rms in the corre
35d40 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20  ct.** form that 
35d50 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 72  refer to the par
35d60 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
35d70 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72  table being quer
35d80 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72  ied..**.** Infor
35d90 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
35da0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
35db0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
35dc0 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63  rderBy[]..** Eac
35dd0 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72  h term of aOrder
35de0 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c  By records a col
35df0 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52  umn of the ORDER
35e00 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a   BY clause..**.*
35e10 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78  * The xBestIndex
35e20 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
35e30 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
35e40 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
35e50 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
35e60 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
35e70 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
35e80 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65 78  r.  If argvIndex
35e90 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  >0 then.** the r
35ea0 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  ight-hand side o
35eb0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
35ec0 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  ing aConstraint[
35ed0 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a  ] is evaluated.*
35ee0 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68  * and becomes th
35ef0 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65  e argvIndex-th e
35f00 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49  ntry in argv.  I
35f10 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  f aConstraintUsa
35f20 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20  ge[].omit.** is 
35f30 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
35f40 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73  onstraint is ass
35f50 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79  umed to be fully
35f60 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a   handled by the.
35f70 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
35f80 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63   and is not chec
35f90 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c  ked again by SQL
35fa0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ite..**.** The i
35fb0 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72  dxNum and idxPtr
35fc0 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f   values are reco
35fd0 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20  rded and passed 
35fe0 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a  into xFilter..**
35ff0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
36000 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20  is used to free 
36010 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f  idxPtr if needTo
36020 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72  FreeIdxPtr is tr
36030 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72  ue..**.** The or
36040 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65  derByConsumed me
36050 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20  ans that output 
36060 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c  from xFilter wil
36070 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
36080 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
36090 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
360a0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
360b0 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
360c0 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
360d0 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
360e0 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61  **.** The estima
360f0 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
36100 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
36110 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
36120 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
36130 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
36140 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
36150 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
36160 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
36170 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
36180 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
36190 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
361a0 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
361b0 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
361c0 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
361d0 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
361e0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
361f0 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
36200 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
36210 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
36220 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
36230 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
36240 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
36250 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
36260 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
36270 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
36280 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
36290 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
362a0 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
362b0 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
362c0 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
362d0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
362e0 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
362f0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
36300 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
36310 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
36320 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
36330 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
36340 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
36350 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
36360 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
36370 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
36380 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
36390 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
363a0 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
363b0 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
363c0 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
363d0 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
363e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
363f0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
36400 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
36410 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
36420 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
36430 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
36440 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
36450 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
36460 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
36470 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
36480 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
36490 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
364a0 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
364b0 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
364c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
364d0 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
364e0 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f 75 74  use */..  /* Out
364f0 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74  puts */.  struct
36500 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
36510 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20  onstraint_usage 
36520 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e  {.    int argvIn
36530 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f  dex;           /
36540 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61  * if >0, constra
36550 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  int is part of a
36560 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a  rgv to xFilter *
36570 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  /.    unsigned c
36580 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f  har omit;      /
36590 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20  * Do not code a 
365a0 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f  test for this co
365b0 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20  nstraint */.  } 
365c0 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67  *aConstraintUsag
365d0 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
365e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
365f0 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
36600 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
36610 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
36620 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
36630 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
36640 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
36650 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
36660 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
36670 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
36680 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
36690 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
366a0 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
366b0 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
366c0 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
366d0 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
366e0 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
366f0 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
36700 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
36710 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
36720 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
36730 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
36740 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  };.#define SQLIT
36750 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
36760 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69  NT_EQ    2.#defi
36770 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
36780 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20  CONSTRAINT_GT   
36790 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
367a0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
367b0 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69  NT_LE    8.#defi
367c0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
367d0 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
367e0 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
367f0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
36800 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65  INT_GE    32.#de
36810 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
36820 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
36830 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  CH 64../*.** CAP
36840 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
36850 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  A Virtual Table 
36860 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b  Implementation {
36870 46 31 38 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F18200}.**.** Th
36880 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
36890 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ed to register a
368a0 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65   new module name
368b0 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65 0a   with an SQLite.
368c0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
368d0 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73  Module names mus
368e0 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
368f0 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67 20  before creating 
36900 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  new.** virtual t
36910 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64  ables on the mod
36920 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75  ule, or before u
36930 73 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e 67  sing preexisting
36940 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
36950 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  es of the module
36960 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36970 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a  _create_module(.
36980 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
36990 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
369a0 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
369b0 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
369c0 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
369d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
369e0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
369f0 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
36a00 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
36a10 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20  e3_module *,    
36a20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
36a30 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
36a40 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 20 20  oid *           
36a50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69            /* Cli
36a60 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
36a70 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
36a80 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
36a90 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
36aa0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d  Virtual Table Im
36ab0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 46 31  plementation {F1
36ac0 38 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  8210}.**.** This
36ad0 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e   routine is iden
36ae0 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71 6c  tical to the sql
36af0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
36b00 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f 76  le() method abov
36b10 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  e,.** except tha
36b20 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65  t it allows a de
36b30 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
36b40 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69 65  n to be specifie
36b50 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e  d. It is.** even
36b60 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74   more experiment
36b70 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73 74  al than the rest
36b80 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
36b90 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69  tables API..*/.i
36ba0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36bb0 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73  e_module_v2(.  s
36bc0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
36bd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
36be0 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
36bf0 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
36c00 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
36c10 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
36c20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
36c30 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
36c40 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
36c50 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20  module *,    /* 
36c60 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
36c70 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
36c80 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20   *,             
36c90 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
36ca0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
36cb0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20  e/xConnect */.  
36cc0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
36cd0 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f  void*)     /* Mo
36ce0 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20  dule destructor 
36cf0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a  function */.);..
36d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36d10 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e  Virtual Table In
36d20 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b 46  stance Object {F
36d30 31 38 30 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  18010}.** KEYWOR
36d40 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62  DS: sqlite3_vtab
36d50 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64  .**.** Every mod
36d60 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
36d70 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
36d80 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ss of the follow
36d90 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ing structure.**
36da0 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70   to describe a p
36db0 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
36dc0 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ce of the module
36dd0 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73  .  Each subclass
36de0 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c   will.** be tail
36df0 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63  ored to the spec
36e00 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68  ific needs of th
36e10 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  e module impleme
36e20 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a  ntation.   The.*
36e30 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69  * purpose of thi
36e40 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20  s superclass is 
36e50 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69  to define certai
36e60 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72  n fields that ar
36e70 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61  e common.** to a
36e80 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ll module implem
36e90 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  entations..**.**
36ea0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
36eb0 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20  methods can set 
36ec0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
36ed0 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a   by assigning a.
36ee0 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  ** string obtain
36ef0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
36f00 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72  mprintf() to zEr
36f10 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f  rMsg.  The metho
36f20 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65  d should.** take
36f30 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70   care that any p
36f40 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66  rior string is f
36f50 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  reed by a call t
36f60 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
36f70 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73  .** prior to ass
36f80 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72  igning a new str
36f90 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ing to zErrMsg. 
36fa0 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   After the error
36fb0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
36fc0 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
36fd0 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
36fe0 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
36ff0 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
37000 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
37010 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
37020 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
37030 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
37040 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a   zeroed.  Note.*
37050 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d  * that sqlite3_m
37060 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
37070 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20  ite3_free() are 
37080 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72  used on the zErr
37090 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e  Msg field.** sin
370a0 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ce virtual table
370b0 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69  s are commonly i
370c0 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f  mplemented in lo
370d0 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
370e0 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f  s which.** do no
370f0 74 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f  t have access to
37100 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28   sqlite3MPrintf(
37110 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65  ) or sqlite3Free
37120 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ()..*/.struct sq
37130 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
37140 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
37150 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
37160 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
37170 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
37180 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
37190 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
371a0 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
371b0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20   internally */. 
371c0 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
371d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
371e0 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
371f0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
37200 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
37210 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
37220 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
37230 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
37240 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
37250 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
37260 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
37270 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20  al Table Cursor 
37280 4f 62 6a 65 63 74 20 20 7b 46 31 38 30 32 30 7d  Object  {F18020}
37290 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
372a0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
372b0 72 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f  r.**.** Every mo
372c0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
372d0 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
372e0 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  ass of the follo
372f0 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a  wing structure.*
37300 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  * to describe cu
37310 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
37320 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61   into the virtua
37330 6c 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20  l table and are 
37340 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
37350 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
37360 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
37370 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
37380 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70  using the.** xOp
37390 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
373a0 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d   module.  Each m
373b0 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
373c0 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65  tion will define
373d0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
373e0 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75  of a cursor stru
373f0 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74  cture to suit it
37400 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  s own needs..**.
37410 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61  ** This supercla
37420 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64  ss exists in ord
37430 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65  er to define fie
37440 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f  lds of the curso
37450 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f  r that.** are co
37460 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c  mmon to all impl
37470 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a  ementations..*/.
37480 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
37490 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
374a0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
374b0 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74  ab;      /* Virt
374c0 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69  ual table of thi
374d0 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a  s cursor */.  /*
374e0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
374f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
37500 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
37510 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
37520 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
37530 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
37540 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66  re The Schema Of
37550 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
37560 20 7b 46 31 38 32 38 30 7d 0a 2a 2a 0a 2a 2a 20   {F18280}.**.** 
37570 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 20  The xCreate and 
37580 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73  xConnect methods
37590 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65   of a module use
375a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
375b0 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65  PI.** to declare
375c0 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65   the format (the
375d0 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74   names and datat
375e0 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ypes of the colu
375f0 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76  mns) of.** the v
37600 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68  irtual tables th
37610 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f  ey implement..*/
37620 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63  .int sqlite3_dec
37630 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65  lare_vtab(sqlite
37640 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
37650 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a  zCreateTable);..
37660 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37670 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74  Overload A Funct
37680 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61  ion For A Virtua
37690 6c 20 54 61 62 6c 65 20 7b 46 31 38 33 30 30 7d  l Table {F18300}
376a0 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
376b0 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64  ables can provid
376c0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  e alternative im
376d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
376e0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73   functions.** us
376f0 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e  ing the xFindFun
37700 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42  ction method.  B
37710 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f  ut global versio
37720 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63  ns of those func
37730 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78  tions.** must ex
37740 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ist in order to 
37750 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  be overloaded..*
37760 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61  *.** This API ma
37770 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
37780 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
37790 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
377a0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
377b0 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
377c0 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
377d0 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
377e0 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
377f0 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
37800 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
37810 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
37820 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70  reated.  The imp
37830 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
37840 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
37850 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
37860 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
37870 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
37880 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
37890 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
378a0 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
378b0 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
378c0 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
378d0 74 6f 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f  to be a place-ho
378e0 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68  lder function th
378f0 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f  at can be overlo
37900 61 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75  aded.** by virtu
37910 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  al tables..**.**
37920 20 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64   This API should
37930 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70   be considered p
37940 61 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75  art of the virtu
37950 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
37960 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20  ce,.** which is 
37970 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
37980 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
37990 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
379a0 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63  e3_overload_func
379b0 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63  tion(sqlite3*, c
379c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
379d0 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b  Name, int nArg);
379e0 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ../*.** The inte
379f0 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
37a00 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
37a10 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f  nism defined abo
37a20 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74  ve (back up.** t
37a30 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61  o a comment rema
37a40 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74  rkably similar t
37a50 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63  o this one) is c
37a60 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
37a70 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
37a80 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
37a90 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
37aa0 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
37ab0 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
37ac0 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
37ad0 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
37ae0 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
37af0 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
37b00 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
37b10 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
37b20 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
37b30 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
37b40 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
37b50 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
37b60 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
37b70 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
37b80 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
37b90 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45  ..**.****** EXPE
37ba0 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65  RIMENTAL - subje
37bb0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74  ct to change wit
37bc0 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a  hout notice ****
37bd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f  **********.*/../
37be0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
37bf0 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70   Handle To An Op
37c00 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38 30 30 7d  en BLOB {F17800}
37c10 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
37c20 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
37c30 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
37c40 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69  open BLOB on whi
37c50 63 68 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61  ch.** incrementa
37c60 6c 20 49 2f 4f 20 63 61 6e 20 62 65 20 70 72 65  l I/O can be pre
37c70 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63  formed..** Objec
37c80 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20  ts of this type 
37c90 61 72 65 20 63 72 65 61 74 65 64 20 62 79 0a 2a  are created by.*
37ca0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
37cb0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73 74  open()] and dest
37cc0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
37cd0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
37ce0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
37cf0 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e  _blob_read()] an
37d00 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  d [sqlite3_blob_
37d10 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61  write()] interfa
37d20 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ces.** can be us
37d30 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ed to read or wr
37d40 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63  ite small subsec
37d50 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c 6f  tions of the blo
37d60 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  b..** The [sqlit
37d70 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
37d80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
37d90 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
37da0 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79  he.** blob in by
37db0 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  tes..*/.typedef 
37dc0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62  struct sqlite3_b
37dd0 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  lob sqlite3_blob
37de0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37df0 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46  F: Open A BLOB F
37e00 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49  or Incremental I
37e10 2f 4f 20 7b 46 31 37 38 31 30 7d 0a 2a 2a 0a 2a  /O {F17810}.**.*
37e20 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
37e30 73 20 6f 70 65 6e 73 20 61 20 68 61 6e 64 6c 65  s opens a handle
37e40 20 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f 63   to the blob loc
37e50 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69  ated.** in row i
37e60 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c  Row, column zCol
37e70 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c  umn, table zTabl
37e80 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44  e in database zD
37e90 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77  b;.** in other w
37ea0 6f 72 64 73 2c 20 20 74 68 65 20 73 61 6d 65 20  ords,  the same 
37eb0 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c 64 20  blob that would 
37ec0 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a  be selected by:.
37ed0 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
37ee0 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d     SELECT zColum
37ef0 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c  n FROM zDb.zTabl
37f00 65 20 57 48 45 52 45 20 72 6f 77 69 64 20 3d 20  e WHERE rowid = 
37f10 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20  iRow;.** </pre> 
37f20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
37f30 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
37f40 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  er is non-zero, 
37f50 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e  the blob is open
37f60 65 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20  ed for .** read 
37f70 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73  and write access
37f80 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c  . If it is zero,
37f90 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65   the blob is ope
37fa0 6e 65 64 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a  ned for read .**
37fb0 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e   access..**.** N
37fc0 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74  ote that the dat
37fd0 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f  abase name is no
37fe0 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74  t the filename t
37ff0 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  hat contains.** 
38000 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
38010 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62   rather the symb
38020 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65  olic name of the
38030 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a   database that.*
38040 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 77 68  * is assigned wh
38050 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
38060 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69  is connected usi
38070 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20  ng [ATTACH]..** 
38080 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74  For the main dat
38090 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20  abase file, the 
380a0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
380b0 20 22 6d 61 69 6e 22 2e 20 20 46 6f 72 0a 2a 2a   "main".  For.**
380c0 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68   TEMP tables, th
380d0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
380e0 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a  is "temp"..**.**
380f0 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
38100 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
38110 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77  rned and the new
38120 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c   .** [sqlite3_bl
38130 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65  ob | blob handle
38140 5d 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  ] is written to 
38150 2a 70 70 42 6c 6f 62 2e 20 0a 2a 2a 20 4f 74 68  *ppBlob. .** Oth
38160 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
38170 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
38180 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 61 6c   and .** any val
38190 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20 2a 70  ue written to *p
381a0 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f 74  pBlob should not
381b0 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65 20   be used by the 
381c0 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 73 20  caller..** This 
381d0 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68  function sets th
381e0 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e 64 6c  e database-handl
381f0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  e error code and
38200 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65   message.** acce
38210 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69  ssible via [sqli
38220 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61  te3_errcode()] a
38230 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
38240 73 67 28 29 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e  sg()]..** .** IN
38250 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
38260 7b 46 31 37 38 31 33 7d 20 41 20 73 75 63 63 65  {F17813} A succe
38270 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
38280 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
38290 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c 54  _blob_open(D,B,T
382a0 2c 43 2c 52 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20  ,C,R,F,P)].**   
382b0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
382c0 20 6f 70 65 6e 73 20 61 6e 20 5b 73 71 6c 69 74   opens an [sqlit
382d0 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20  e3_blob] object 
382e0 50 20 6f 6e 20 74 68 65 20 62 6c 6f 62 0a 2a 2a  P on the blob.**
382f0 20 20 20 20 20 20 20 20 20 20 69 6e 20 63 6f 6c            in col
38300 75 6d 6e 20 43 20 6f 66 20 74 61 62 6c 65 20 54  umn C of table T
38310 20 69 6e 20 64 61 74 61 62 61 73 65 20 42 20 6f   in database B o
38320 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
38330 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
38340 20 7b 46 31 37 38 31 34 7d 20 41 20 73 75 63 63   {F17814} A succ
38350 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
38360 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c  n of [sqlite3_bl
38370 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d 20  ob_open(D,...)] 
38380 73 74 61 72 74 73 0a 2a 2a 20 20 20 20 20 20 20  starts.**       
38390 20 20 20 61 20 6e 65 77 20 74 72 61 6e 73 61 63     a new transac
383a0 74 69 6f 6e 20 6f 6e 20 5b 64 61 74 61 62 61 73  tion on [databas
383b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
383c0 69 66 20 74 68 61 74 20 63 6f 6e 6e 65 63 74 69  if that connecti
383d0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  on.**          i
383e0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69 6e  s not already in
383f0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a   a transaction..
38400 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 36 7d 20 54  **.** {F17816} T
38410 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
38420 5f 6f 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c  _open(D,B,T,C,R,
38430 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
38440 6f 70 65 6e 73 20 74 68 65 20 62 6c 6f 62 0a 2a  opens the blob.*
38450 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72  *          for r
38460 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61 63  ead and write ac
38470 63 65 73 73 20 69 66 20 61 6e 64 20 6f 6e 6c 79  cess if and only
38480 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65   if the F parame
38490 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
384a0 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a  is non-zero..**.
384b0 2a 2a 20 7b 46 31 37 38 31 39 7d 20 54 68 65 20  ** {F17819} The 
384c0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
384d0 65 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  en()] interface 
384e0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
384f0 4f 4b 5d 20 6f 6e 20 0a 2a 2a 20 20 20 20 20 20  OK] on .**      
38500 20 20 20 20 73 75 63 63 65 73 73 20 61 6e 64 20      success and 
38510 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
38520 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66  error code] on f
38530 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ailure..**.** {F
38540 31 37 38 32 31 7d 20 49 66 20 61 6e 20 65 72 72  17821} If an err
38550 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
38560 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b   evaluation of [
38570 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
38580 6e 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  n(D,...)].**    
38590 20 20 20 20 20 20 74 68 65 6e 20 73 75 62 73 65        then subse
385a0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
385b0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
385c0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
385d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
385e0 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  (D)], and [sqlit
385f0 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 20  e3_errmsg16(D)] 
38600 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20  will return.**  
38610 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74          informat
38620 69 6f 6e 20 61 70 70 72 6f 70 72 61 74 65 20 66  ion approprate f
38630 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e 0a 2a  or that error..*
38640 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
38650 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74  ob_open(.  sqlit
38660 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  e3*,.  const cha
38670 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20  r *zDb,.  const 
38680 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20  char *zTable,.  
38690 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
386a0 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69  umn,.  sqlite3_i
386b0 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74  nt64 iRow,.  int
386c0 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65   flags,.  sqlite
386d0 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a  3_blob **ppBlob.
386e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
386f0 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 4c 4f  EF:  Close A BLO
38700 42 20 48 61 6e 64 6c 65 20 7b 46 31 37 38 33 30  B Handle {F17830
38710 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61 6e  }.**.** Close an
38720 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62   open [sqlite3_b
38730 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c  lob | blob handl
38740 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e  e]..**.** Closin
38750 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63  g a BLOB shall c
38760 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e 74  ause the current
38770 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
38780 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65  commit.** if the
38790 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20  re are no other 
387a0 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e  BLOBs, no pendin
387b0 67 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  g prepared state
387c0 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ments, and the.*
387d0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
387e0 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75 74 6f  ction is in auto
387f0 63 6f 6d 6d 69 74 20 6d 6f 64 65 2e 0a 2a 2a 20  commit mode..** 
38800 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65  If any writes we
38810 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42  re made to the B
38820 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20  LOB, they might 
38830 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65  be held in cache
38840 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c  .** until the cl
38850 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66  ose operation if
38860 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 20   they will fit. 
38870 7b 45 4e 44 7d 0a 2a 2a 20 43 6c 6f 73 69 6e 67  {END}.** Closing
38880 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20   the BLOB often 
38890 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67  forces the chang
388a0 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73  es.** out to dis
388b0 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20  k and so if any 
388c0 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72  I/O errors occur
388d0 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65  , they will like
388e0 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74  ly occur.** at t
388f0 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  he time when the
38900 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e   BLOB is closed.
38910 20 20 7b 46 31 37 38 33 33 7d 20 41 6e 79 20 65    {F17833} Any e
38920 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
38930 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69   during.** closi
38940 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ng are reported 
38950 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  as a non-zero re
38960 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  turn value..**.*
38970 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c  * The BLOB is cl
38980 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e  osed uncondition
38990 61 6c 6c 79 2e 20 20 45 76 65