/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 0f4f33b54824cc8077c028a85a1dbd8a3df4fa73:


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 32 30 20 32 30 30 38 2f  in,v 1.320 2008/
05f0: 30 36 2f 30 35 20 31 31 3a 33 39 3a 31 31 20 64  06/05 11:39:11 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 20  ase connection} 
16d0: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
16e0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  tions}.**.** Eac
16f0: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
1700: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
1710: 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65 72  ented by pointer
1720: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
1730: 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75 65  of the.** opaque
1740: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
1750: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
1760: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
1770: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
1780: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
1790: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
17a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
17b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
17c0: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
17d0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
17e0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
17f0: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 0a  ts constructors.
1800: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
1810: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73 20  close()] is its 
1820: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
1830: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
1840: 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
1850: 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74 65  (such as [sqlite
1860: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1870: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1880: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
1890: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
18a0: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
18b0: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
18c0: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
18d0: 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  s on this.** obj
18e0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
18f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
1900: 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  qlite3;.../*.** 
1910: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74  CAPI3REF: 64-Bit
1920: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b   Integer Types {
1930: 46 31 30 32 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F10200}.** KEYWO
1940: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
1950: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
1960: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1970: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
1980: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
1990: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
19a0: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
19b0: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
19c0: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
19d0: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
19e0: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
19f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1a00: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
1a10: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
1a20: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
1a30: 79 70 65 0a 2a 2a 20 64 65 66 69 6e 69 74 69 6f  ype.** definitio
1a40: 6e 73 2e 20 20 54 68 65 20 73 71 6c 69 74 65 5f  ns.  The sqlite_
1a50: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
1a60: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
1a70: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 65 64 20 66  e.** supported f
1a80: 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1a90: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
1aa0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1ab0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30 31  S:.**.** {F10201
1ac0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 69 6e  } The [sqlite_in
1ad0: 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  t64] and [sqlite
1ae0: 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 73 20 73  3_int64] types s
1af0: 70 65 63 69 66 79 20 61 0a 2a 2a 20 20 20 20 20  pecify a.**     
1b00: 20 20 20 20 20 36 34 2d 62 69 74 20 73 69 67 6e       64-bit sign
1b10: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1b20: 2a 20 7b 46 31 30 32 30 32 7d 20 54 68 65 20 5b  * {F10202} The [
1b30: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61  sqlite_uint64] a
1b40: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74  nd [sqlite3_uint
1b50: 36 34 5d 20 74 79 70 65 73 20 73 70 65 63 69 66  64] types specif
1b60: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  y.**          a 
1b70: 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
1b80: 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 64  integer..*/.#ifd
1b90: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
1ba0: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
1bb0: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
1bc0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
1bd0: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
1be0: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
1bf0: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
1c00: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
1c10: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
1c20: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
1c30: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
1c40: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
1c50: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
1c60: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
1c70: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
1c80: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
1c90: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
1ca0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
1cb0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
1cc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
1cd0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
1ce0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
1cf0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
1d00: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
1d10: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
1d20: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
1d30: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
1d40: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
1d50: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
1d60: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
1d70: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
1d80: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
1d90: 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69  ting-point.*/.#i
1da0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
1db0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
1dc0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
1dd0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
1de0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1df0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
1e00: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1e10: 69 6f 6e 20 7b 46 31 32 30 31 30 7d 0a 2a 2a 0a  ion {F12010}.**.
1e20: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1e30: 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  is the destructo
1e40: 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  r for the [sqlit
1e50: 65 33 5d 20 6f 62 6a 65 63 74 2e 20 20 0a 2a 2a  e3] object.  .**
1e60: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1e70: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
1e80: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
1e90: 6c 69 7a 65 5d 20 61 6c 6c 0a 2a 2a 20 5b 70 72  lize] all.** [pr
1ea0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1eb0: 73 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  s] and.** [sqlit
1ec0: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20  e3_blob_close | 
1ed0: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 73 71 6c 69  close] all [sqli
1ee0: 74 65 33 5f 62 6c 6f 62 20 7c 20 42 4c 4f 42 73  te3_blob | BLOBs
1ef0: 5d 20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ] .** associated
1f00: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
1f10: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
1f20: 0a 2a 2a 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  .** to attemptin
1f30: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 5b  g to close the [
1f40: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
1f50: 0a 2a 2a 0a 2a 2a 20 3c 74 6f 64 6f 3e 57 68 61  .**.** <todo>Wha
1f60: 74 20 68 61 70 70 65 6e 73 20 74 6f 20 70 65 6e  t happens to pen
1f70: 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f 6e  ding transaction
1f80: 73 3f 20 20 41 72 65 20 74 68 65 79 0a 2a 2a 20  s?  Are they.** 
1f90: 72 6f 6c 6c 65 64 20 62 61 63 6b 2c 20 6f 72 20  rolled back, or 
1fa0: 61 62 61 6e 64 6f 6e 65 64 3f 3c 2f 74 6f 64 6f  abandoned?</todo
1fb0: 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  >.**.** INVARIAN
1fc0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  TS:.**.** {F1201
1fd0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1fe0: 63 6c 6f 73 65 28 29 5d 20 69 6e 74 65 72 66 61  close()] interfa
1ff0: 63 65 20 64 65 73 74 72 6f 79 73 20 61 6e 20 5b  ce destroys an [
2000: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a  sqlite3] object.
2010: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
2020: 63 61 74 65 64 20 62 79 20 61 20 70 72 69 6f 72  cated by a prior
2030: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2040: 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 20 20  3_open()],.**   
2050: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2060: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73  open16()], or [s
2070: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2080: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 32  ]..**.** {F12012
2090: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
20a0: 6c 6f 73 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e  lose()] function
20b0: 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 20 6d 65   releases all me
20c0: 6d 6f 72 79 20 75 73 65 64 20 62 79 20 74 68 65  mory used by the
20d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
20e0: 6e 65 63 74 69 6f 6e 20 61 6e 64 20 63 6c 6f 73  nection and clos
20f0: 65 73 20 61 6c 6c 20 6f 70 65 6e 20 66 69 6c 65  es all open file
2100: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 33  s..**.** {F12013
2110: 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  } If the databas
2120: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f 6e  e connection con
2130: 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
2140: 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2150: 65 6d 65 6e 74 73 5d 20 74 68 61 74 20 68 61 76  ements] that hav
2160: 65 20 6e 6f 74 20 62 65 65 6e 0a 2a 2a 20 20 20  e not been.**   
2170: 20 20 20 20 20 20 20 66 69 6e 61 6c 69 7a 65 64         finalized
2180: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2190: 61 6c 69 7a 65 28 29 5d 2c 20 74 68 65 6e 20 5b  alize()], then [
21a0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
21b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
21c0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
21d0: 59 5d 20 61 6e 64 20 6c 65 61 76 65 73 20 74 68  Y] and leaves th
21e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
21f0: 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 34  n..**.** {F12014
2200: 7d 20 47 69 76 69 6e 67 20 73 71 6c 69 74 65 33  } Giving sqlite3
2210: 5f 63 6c 6f 73 65 28 29 20 61 20 4e 55 4c 4c 20  _close() a NULL 
2220: 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
2230: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
2240: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
2250: 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 35 7d 20 54  **.** {U12015} T
2260: 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
2270: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2280: 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 5b 73 71  ] must be an [sq
2290: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a 2a 2a  lite3] object.**
22a0: 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65            pointe
22b0: 72 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  r previously obt
22c0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
22d0: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 74  te3_open()] or t
22e0: 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
22f0: 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 4e  equivalent, or N
2300: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30  ULL..**.** {U120
2310: 31 36 7d 20 54 68 65 20 70 61 72 61 6d 65 74 65  16} The paramete
2320: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
2330: 6f 73 65 28 29 5d 20 6d 75 73 74 20 6e 6f 74 20  ose()] must not 
2340: 68 61 76 65 20 62 65 65 6e 20 70 72 65 76 69 6f  have been previo
2350: 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  usly.**         
2360: 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20   closed..*/.int 
2370: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71  sqlite3_close(sq
2380: 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  lite3 *);../*.**
2390: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
23a0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
23b0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
23c0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
23d0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
23e0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
23f0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
2400: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
2410: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
2420: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
2430: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
2440: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
2450: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
2460: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
2470: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
2480: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 46  ion Interface {F
2490: 31 32 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12100}.**.** The
24a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
24b0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
24c0: 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66  onvenient way of
24d0: 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 6f 6e 65 20   running.** one 
24e0: 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 61 74  or more SQL stat
24f0: 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 61  ements without a
2500: 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20   lot of C code. 
2510: 20 54 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   The.** SQL stat
2520: 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73 65  ements are passe
2530: 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f  d in as the seco
2540: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
2550: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
2560: 29 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65 6e  ).  The statemen
2570: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
2580: 20 6f 6e 65 20 62 79 20 6f 6e 65 0a 2a 2a 20 75   one by one.** u
2590: 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20 65  ntil either an e
25a0: 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72  rror or an inter
25b0: 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65  rupt is encounte
25c0: 72 65 64 20 6f 72 0a 2a 2a 20 75 6e 74 69 6c 20  red or.** until 
25d0: 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e  they are all don
25e0: 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 72 61  e.  The 3rd para
25f0: 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 74 69  meter is an opti
2600: 6f 6e 61 6c 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  onal.** callback
2610: 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
2620: 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72   once for each r
2630: 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 79 20  ow of any query 
2640: 72 65 73 75 6c 74 73 0a 2a 2a 20 70 72 6f 64 75  results.** produ
2650: 63 65 64 20 62 79 20 74 68 65 20 53 51 4c 20 73  ced by the SQL s
2660: 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20  tatements.  The 
2670: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 65  5th parameter te
2680: 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20  lls where.** to 
2690: 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20  write any error 
26a0: 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20  messages..**.** 
26b0: 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  The error messag
26c0: 65 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  e passed back th
26d0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
26e0: 72 61 6d 65 74 65 72 20 69 73 20 68 65 6c 64 0a  rameter is held.
26f0: 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ** in memory obt
2700: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2710: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
2720: 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  To avoid a memor
2730: 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63  y leak,.** the c
2740: 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61 74 69  alling applicati
2750: 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b  on should call [
2760: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
2770: 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20  on any error.** 
2780: 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64  message returned
2790: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
27a0: 20 70 61 72 61 6d 65 74 65 72 20 77 68 65 6e 20   parameter when 
27b0: 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
27c0: 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72  using.** the err
27d0: 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
27e0: 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
27f0: 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 32 6e  tement in the 2n
2800: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  d parameter is N
2810: 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
2820: 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73  string.** or a s
2830: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
2840: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
2850: 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   and comments, t
2860: 68 65 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  hen SQL.** state
2870: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
2880: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
2890: 62 61 73 65 20 69 73 20 75 6e 63 68 61 6e 67 65  base is unchange
28a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
28b0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
28c0: 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
28d0: 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66  nted in terms of
28e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
28f0: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
2900: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
2910: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2920: 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  ize()]..** The s
2930: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f  qlite3_exec() ro
2940: 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69  utine does nothi
2950: 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ng to the databa
2960: 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  se that cannot b
2970: 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71  e done.** by [sq
2980: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2990: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
29a0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
29b0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
29c0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
29d0: 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 31 30  S:.** .** {F1210
29e0: 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
29f0: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
2a00: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
2a10: 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20 20  C,A,E)].**      
2a20: 20 20 20 20 73 68 61 6c 6c 20 65 76 61 6c 75 61      shall evalua
2a30: 74 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55 54  te all of the UT
2a40: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 20 73 65 6d  F-8 encoded, sem
2a50: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
2a60: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  ,.**          SQ
2a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
2a80: 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
2a90: 74 65 64 20 73 74 72 69 6e 67 20 53 20 77 69 74  ted string S wit
2aa0: 68 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hin the.**      
2ab0: 20 20 20 20 63 6f 6e 74 65 78 74 20 6f 66 20 74      context of t
2ac0: 68 65 20 44 20 5b 64 61 74 61 62 61 73 65 20 63  he D [database c
2ad0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
2ae0: 2a 20 7b 46 31 32 31 30 32 7d 20 49 66 20 74 68  * {F12102} If th
2af0: 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e S parameter to
2b00: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
2b10: 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55  ,S,C,A,E)] is NU
2b20: 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  LL then.**      
2b30: 20 20 20 20 74 68 65 20 61 63 74 69 6f 6e 73 20      the actions 
2b40: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
2b50: 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 73 61   shall be the sa
2b60: 6d 65 20 61 73 20 69 66 20 74 68 65 0a 2a 2a 20  me as if the.** 
2b70: 20 20 20 20 20 20 20 20 20 53 20 70 61 72 61 6d           S param
2b80: 65 74 65 72 20 77 68 65 72 65 20 61 6e 20 65 6d  eter where an em
2b90: 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
2ba0: 2a 20 7b 46 31 32 31 30 34 7d 20 54 68 65 20 72  * {F12104} The r
2bb0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b  eturn value of [
2bc0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
2bd0: 73 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45  shall be [SQLITE
2be0: 5f 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20  _OK] if all.**  
2bf0: 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74          SQL stat
2c00: 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63 65  ements run succe
2c10: 73 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63  ssfully and to c
2c20: 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
2c30: 20 7b 46 31 32 31 30 35 7d 20 54 68 65 20 72 65   {F12105} The re
2c40: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73  turn value of [s
2c50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73  qlite3_exec()] s
2c60: 68 61 6c 6c 20 62 65 20 61 6e 20 61 70 70 72 6f  hall be an appro
2c70: 70 72 69 61 74 65 20 0a 2a 2a 20 20 20 20 20 20  priate .**      
2c80: 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72      non-zero [er
2c90: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
2ca0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
2cb0: 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ails..**.** {F12
2cc0: 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d  107} If one or m
2cd0: 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ore of the SQL s
2ce0: 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64  tatements handed
2cf0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
2d00: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
2d10: 20 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20   return results 
2d20: 61 6e 64 20 74 68 65 20 33 72 64 20 70 61 72 61  and the 3rd para
2d30: 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  meter is not NUL
2d40: 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  L, then.**      
2d50: 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b      the callback
2d60: 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66   function specif
2d70: 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70  ied by the 3rd p
2d80: 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62  arameter shall b
2d90: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
2da0: 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  voked once for e
2db0: 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75 6c  ach row of resul
2dc0: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 30  t..**.** {F12110
2dd0: 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  } If the callbac
2de0: 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  k returns a non-
2df0: 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e 20  zero value then 
2e00: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2e10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
2e20: 6c 6c 20 61 62 6f 72 74 20 74 68 65 20 53 51 4c  ll abort the SQL
2e30: 20 73 74 61 74 65 6d 65 6e 74 20 69 74 20 69 73   statement it is
2e40: 20 63 75 72 72 65 6e 74 6c 79 20 65 76 61 6c 75   currently evalu
2e50: 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20 20  ating,.**       
2e60: 20 20 20 73 6b 69 70 20 61 6c 6c 20 73 75 62 73     skip all subs
2e70: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
2e80: 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65 74 75 72  ments, and retur
2e90: 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  n [SQLITE_ABORT]
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 33 7d  ..**.** {F12113}
2eb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
2ec0: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  ec()] routine sh
2ed0: 61 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74 68  all pass its 4th
2ee0: 20 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75   parameter throu
2ef0: 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  gh.**          a
2f00: 73 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  s the 1st parame
2f10: 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ter of the callb
2f20: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ack..**.** {F121
2f30: 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  16} The [sqlite3
2f40: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
2f50: 20 73 65 74 73 20 74 68 65 20 32 6e 64 20 70 61   sets the 2nd pa
2f60: 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a  rameter of its.*
2f70: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
2f80: 61 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e 75  ack to be the nu
2f90: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2fa0: 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2fb0: 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ow of.**        
2fc0: 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20    result..**.** 
2fd0: 7b 46 31 32 31 31 39 7d 20 54 68 65 20 5b 73 71  {F12119} The [sq
2fe0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f  lite3_exec()] ro
2ff0: 75 74 69 6e 65 20 73 65 74 73 20 74 68 65 20 33  utine sets the 3
3000: 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  rd parameter of 
3010: 69 74 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  its .**         
3020: 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
3030: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3040: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3050: 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20  holding the.**  
3060: 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 66          values f
3070: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69  or each column i
3080: 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  n the current re
3090: 73 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a  sult set row as.
30a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61  **          obta
30b0: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
30c0: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 32  ]..**.** {F12122
30e0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
30f0: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73  xec()] routine s
3100: 65 74 73 20 74 68 65 20 34 74 68 20 70 61 72 61  ets the 4th para
3110: 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20  meter of its.** 
3120: 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
3130: 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79  k to be an array
3140: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3150: 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20  strings holding 
3160: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
3170: 6e 61 6d 65 73 20 6f 66 20 72 65 73 75 6c 74 20  names of result 
3180: 63 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61 69  columns as obtai
3190: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
31a0: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
31b0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 35 7d  ..**.** {F12125}
31c0: 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
31d0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
31e0: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 4e 55 4c  3_exec()] is NUL
31f0: 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  L then.**       
3200: 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63     [sqlite3_exec
3210: 28 29 5d 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ()] never invoke
3220: 73 20 61 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  s a callback.  A
3230: 6c 6c 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20  ll query.**     
3240: 20 20 20 20 20 72 65 73 75 6c 74 73 20 61 72 65       results are
3250: 20 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61 72   silently discar
3260: 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ded..**.** {F121
3270: 33 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20  31} If an error 
3280: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72  occurs while par
3290: 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69  sing or evaluati
32a0: 6e 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51  ng any of the SQ
32b0: 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61  L.**          ha
32c0: 6e 64 65 64 20 69 6e 20 74 68 65 20 53 20 70 61  nded in the S pa
32d0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
32e0: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
32f0: 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20  ,E)] and if.**  
3300: 20 20 20 20 20 20 20 20 74 68 65 20 45 20 70 61          the E pa
3310: 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e  rameter is not N
3320: 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74  ULL, then [sqlit
3330: 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c  e3_exec()] shall
3340: 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20   store.**       
3350: 20 20 20 69 6e 20 2a 45 20 61 6e 20 61 70 70 72     in *E an appr
3360: 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
3370: 73 73 61 67 65 20 77 72 69 74 74 65 6e 20 69 6e  ssage written in
3380: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
3390: 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ed.**          f
33a0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
33b0: 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  loc()]..**.** {F
33c0: 31 32 31 33 34 7d 20 54 68 65 20 5b 73 71 6c 69  12134} The [sqli
33d0: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
33e0: 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  ,E)] routine sha
33f0: 6c 6c 20 73 65 74 20 74 68 65 20 76 61 6c 75 65  ll set the value
3400: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
3410: 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20  *E to NULL if E 
3420: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
3430: 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72  there are no err
3440: 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ors..**.** {F121
3450: 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  37} The [sqlite3
3460: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3470: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
3480: 20 73 65 74 20 74 68 65 20 65 72 72 6f 72 20 63   set the error c
3490: 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
34a0: 61 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 65  and message acce
34b0: 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69  ssible via [sqli
34c0: 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a  te3_errcode()],.
34d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
34e0: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
34f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
3500: 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  msg16()]..**.** 
3510: 7b 46 31 32 31 33 38 7d 20 49 66 20 74 68 65 20  {F12138} If the 
3520: 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  S parameter to [
3530: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
3540: 2c 43 2c 41 2c 45 29 5d 20 69 73 20 61 20 6e 75  ,C,A,E)] is a nu
3550: 6c 6c 20 6f 72 20 65 6d 70 74 79 0a 2a 2a 20 20  ll or empty.**  
3560: 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 6f          string o
3570: 72 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69  r contains nothi
3580: 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68  ng other than wh
3590: 69 74 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e  itespace, commen
35a0: 74 73 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 20 20  ts, and/or.**   
35b0: 20 20 20 20 20 20 20 73 65 6d 69 63 6f 6c 6f 6e         semicolon
35c0: 73 2c 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20  s, then results 
35d0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  of [sqlite3_errc
35e0: 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ode()],.**      
35f0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
3600: 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  msg()], and [sql
3610: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
3620: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
3630: 6c 6c 20 72 65 73 65 74 20 74 6f 20 69 6e 64 69  ll reset to indi
3640: 63 61 74 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a  cate no errors..
3650: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
3660: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 31  S:.**.** {U12141
3670: 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
3680: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3690: 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62  3_exec()] must b
36a0: 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f  e an valid and o
36b0: 70 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pen.**          
36c0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36d0: 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31  tion]..**.** {U1
36e0: 32 31 34 32 7d 20 54 68 65 20 64 61 74 61 62 61  2142} The databa
36f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
3700: 73 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64  st not be closed
3710: 20 77 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20   while.**       
3720: 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63     [sqlite3_exec
3730: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ()] is running..
3740: 2a 2a 20 0a 2a 2a 20 7b 55 31 32 31 34 33 7d 20  ** .** {U12143} 
3750: 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
3760: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
3770: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
3780: 20 74 6f 20 66 72 65 65 0a 2a 2a 20 20 20 20 20   to free.**     
3790: 20 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79 20       the memory 
37a0: 74 68 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20  that *errmsg is 
37b0: 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74  left pointing at
37c0: 20 6f 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a   once the error.
37d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 73 73  **          mess
37e0: 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  age is no longer
37f0: 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b   needed..**.** {
3800: 55 31 32 31 34 35 7d 20 54 68 65 20 53 51 4c 20  U12145} The SQL 
3810: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
3820: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  n the 2nd parame
3830: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3840: 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20  exec()].**      
3850: 20 20 20 20 6d 75 73 74 20 72 65 6d 61 69 6e 20      must remain 
3860: 75 6e 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20  unchanged while 
3870: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3880: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
3890: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
38a0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
38b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
38d0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
38e0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
38f0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3910: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3920: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
3930: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
3940: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3950: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
3960: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
3970: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
3980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3990: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
39a0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
39b0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
39c0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
39d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
39e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
39f0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3a00: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3a10: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3a20: 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 31 30  lt Codes {F10210
3a30: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  }.** KEYWORDS: S
3a40: 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20  QLITE_OK {error 
3a50: 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64  code} {error cod
3a60: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
3a70: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
3a80: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
3a90: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
3aa0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
3ab0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
3ac0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73  r to indicates s
3ad0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3ae0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3af0: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3b00: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3b10: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3b20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3b30: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3b40: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3b50: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3b60: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3b70: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3b80: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3b90: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ba0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3bb0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3bc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3bd0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3be0: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3bf0: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3c00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3c10: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3c20: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3c30: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3c50: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3c60: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3c70: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3c80: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3c90: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3ca0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3cb0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3cc0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3cd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
3ce0: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
3cf0: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
3d00: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
3d10: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3d20: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
3d30: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
3d40: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
3d50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
3d60: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
3d70: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
3d80: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
3d90: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
3da0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
3db0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
3dc0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
3dd0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
3de0: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
3df0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
3e00: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
3e10: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
3e20: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
3e30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3e40: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
3e50: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
3e60: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
3e70: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
3e80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
3e90: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
3ea0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
3eb0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
3ec0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
3ed0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
3ee0: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
3ef0: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
3f00: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
3f10: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
3f20: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
3f30: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
3f40: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
3f50: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
3f60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
3f70: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
3f80: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
3f90: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
3fa0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
3fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
3fc0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
3fd0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
3fe0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
3ff0: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4000: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4010: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4020: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4030: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4040: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4050: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4060: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
4080: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
4090: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
40a0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
40b0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
40c0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
40d0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
40e0: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
40f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4100: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4110: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4120: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4140: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4150: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4160: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4170: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
4180: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
4190: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
41a0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
41b0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
41c0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
41d0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
41e0: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
41f0: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4210: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4220: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4230: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4240: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4260: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4270: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
4280: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
4290: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
42a0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
42b0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
42c0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
42d0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
42e0: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
42f0: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4300: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4310: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4320: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4330: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4340: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4360: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4370: 65 73 20 7b 46 31 30 32 32 30 7d 0a 2a 2a 20 4b  es {F10220}.** K
4380: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4390: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  ed error code} {
43a0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
43b0: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
43c0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
43d0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
43e0: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20   In its default 
43f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53  configuration, S
4400: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e  QLite API routin
4410: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  es return one of
4420: 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   26 integer.** [
4430: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
4440: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4450: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4460: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a  has shown that.*
4470: 2a 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65 20  * many of these 
4480: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4490: 20 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61 69   too course-grai
44a0: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
44b0: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
44c0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
44d0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
44e0: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
44f0: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4500: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4510: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4520: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4530: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4540: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4550: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4560: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4570: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4580: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4590: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
45a0: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
45b0: 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e  rrors. The exten
45c0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
45d0: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20   are enabled or 
45e0: 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20  disabled.** for 
45f0: 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
4600: 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74  nnection using t
4610: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  he [sqlite3_exte
4620: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
4630: 73 28 29 5d 0a 2a 2a 20 41 50 49 2e 0a 2a 2a 20  s()].** API..** 
4640: 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20  .** Some of the 
4650: 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64  available extend
4660: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4670: 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e  are listed here.
4680: 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65  .** One may expe
4690: 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ct the number of
46a0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
46b0: 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65   codes will be e
46c0: 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69  xpand.** over ti
46d0: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
46e0: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4700: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4710: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4720: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4730: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4740: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4750: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4760: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4770: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4780: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4790: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
47a0: 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  .** .** INVARIAN
47b0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32  TS:.**.** {F1022
47c0: 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20  3} The symbolic 
47d0: 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65  name for an exte
47e0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
47f0: 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e 73   always contains
4800: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72  .**          a r
4810: 65 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72  elated primary r
4820: 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20  esult code as a 
4830: 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 46  prefix..**.** {F
4840: 31 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72  10224} Primary r
4850: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73  esult code names
4860: 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c   contain a singl
4870: 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 2e  e "_" character.
4880: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 35 7d 20  .**.** {F10225} 
4890: 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  Extended result 
48a0: 63 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61  code names conta
48b0: 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22  in two or more "
48c0: 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  _" characters..*
48d0: 2a 0a 2a 2a 20 7b 46 31 30 32 32 36 7d 20 54 68  *.** {F10226} Th
48e0: 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  e numeric value 
48f0: 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72  of an extended r
4900: 65 73 75 6c 74 20 63 6f 64 65 20 63 6f 6e 74 61  esult code conta
4910: 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
4920: 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75      numeric valu
4930: 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70  e of its corresp
4940: 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72  onding primary r
4950: 65 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a  esult code in.**
4960: 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6c 65            its le
4970: 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20  ast significant 
4980: 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69  8 bits..*/.#defi
4990: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
49a0: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
49b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
49c0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
49d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
49e0: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
49f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4a00: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4a10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4a20: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4a30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4a40: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4a50: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4a60: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
4a70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4a80: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
4a90: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
4aa0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
4ab0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
4ac0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4ad0: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
4ae0: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
4af0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
4b00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b10: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
4b20: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b30: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
4b40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4b50: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
4b60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4b70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
4b80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4b90: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
4ba0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4bb0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
4bc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4bd0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
4be0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4bf0: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
4c00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c10: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
4c20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c30: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
4c40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c50: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
4c60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c70: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
4c80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c90: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
4ca0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4cb0: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
4cc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4cd0: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
4ce0: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
4cf0: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
4d00: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
4d10: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
4d20: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
4d30: 73 20 7b 46 31 30 32 33 30 7d 0a 2a 2a 0a 2a 2a  s {F10230}.**.**
4d40: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
4d50: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
4d60: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
4d70: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
4d80: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
4d90: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
4da0: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
4db0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
4dc0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
4dd0: 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  hod of the.** [s
4de0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
4df0: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
4e00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
4e10: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
4e20: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
4e30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
4e40: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
4e50: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
4e60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
4e70: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
4e80: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
4e90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
4ea0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
4eb0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
4ec0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
4ed0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
4ee0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
4ef0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
4f00: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
4f10: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
4f20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
4f30: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
4f40: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
4f50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
4f60: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
4f70: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
4f80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
4f90: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
4fa0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
4fb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
4fc0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
4fd0: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
4fe0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
4ff0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
5000: 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53  002000.#define S
5010: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
5020: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
5030: 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  004000../*.** CA
5040: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
5050: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b  haracteristics {
5060: 46 31 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10240}.**.** Th
5070: 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c  e xDeviceCapabil
5080: 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20  ities method of 
5090: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
50a0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
50b0: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
50c0: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
50d0: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
50e0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
50f0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
5100: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
5110: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
5120: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
5130: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
5140: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
5150: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5160: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
5170: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
5180: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
5190: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
51a0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
51b0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
51c0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
51d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
51e0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
51f0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
5200: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
5210: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
5220: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
5230: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
5240: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
5250: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
5260: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
5270: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
5280: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
5290: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
52a0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
52b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
52c0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
52d0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
52e0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
52f0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
5300: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
5310: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
5320: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
5330: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5340: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
5350: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
5360: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
5370: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
5380: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
5390: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
53a0: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
53b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
53c0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
53d0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
53e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
53f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
5400: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
5410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5420: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
5430: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
5440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5450: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
5460: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5480: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5490: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
54a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
54b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
54c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
54d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
54e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
54f0: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
5500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5510: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
5520: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
5530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5540: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
5550: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
5560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5570: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5580: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
5590: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
55a0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
55b0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
55c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
55d0: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
55e0: 76 65 6c 73 20 7b 46 31 30 32 35 30 7d 0a 2a 2a  vels {F10250}.**
55f0: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
5600: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
5610: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
5620: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
5630: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
5640: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
5650: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
5660: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
5670: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
5680: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
5690: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
56a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
56b0: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
56c0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
56d0: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
56f0: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
5700: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5710: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
5720: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
5730: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
5740: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
5750: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
5760: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
5770: 46 6c 61 67 73 20 7b 46 31 30 32 36 30 7d 0a 2a  Flags {F10260}.*
5780: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
5790: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
57a0: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
57b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
57c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
57d0: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
57e0: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  nation of.** the
57f0: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
5800: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
5810: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
5820: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
5830: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
5840: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
5850: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
5860: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
5870: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
5880: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
5890: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
58a0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
58b0: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
58c0: 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54 45 5f  hed. The SQLITE_
58d0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c 61 67  SYNC_NORMAL flag
58e0: 20 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73   means .** to us
58f0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
5900: 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65 20   semantics. The 
5910: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5920: 20 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a 20   flag means .** 
5930: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20  to use Mac OS-X 
5940: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
5950: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
5960: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
5970: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
5980: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
5990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
59a0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
59b0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
59c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
59d0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
59e0: 30 31 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  010.../*.** CAPI
59f0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
5a00: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
5a10: 64 6c 65 20 7b 46 31 31 31 31 30 7d 0a 2a 2a 0a  dle {F11110}.**.
5a20: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5a30: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5a40: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5a50: 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a  ile in the OS.**
5a60: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5a70: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
5a80: 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65   interface imple
5a90: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
5aa0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
5ab0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
5ac0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
5ad0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
5ae0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
5af0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
5b00: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
5b10: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
5b20: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5b30: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
5b40: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
5b50: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
5b60: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
5b70: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
5b80: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
5b90: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
5ba0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
5bb0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
5bc0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
5bd0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
5be0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
5bf0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
5c00: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
5c10: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
5c20: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
5c30: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
5c40: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20   Methods Object 
5c50: 7b 46 31 31 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 45  {F11120}.**.** E
5c60: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
5c70: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
5c80: 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68  _vfs] xOpen meth
5c90: 6f 64 20 63 6f 6e 74 61 69 6e 73 20 61 20 70 6f  od contains a po
5ca0: 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 69  inter to.** an i
5cb0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
5cc0: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
5cd0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
5ce0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65 64  .** methods used
5cf0: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
5d00: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ous operations a
5d10: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
5d20: 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  file..**.** The 
5d30: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
5d40: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
5d50: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
5d60: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
5d70: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
5d80: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
5d90: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
5da0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 20  rmal fsync()..* 
5db0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
5dc0: 63 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d 58  ce is an.** OS-X
5dd0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
5de0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e    The SQLITE_SYN
5df0: 43 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 79 20  C_DATA flag may 
5e00: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a 2a 2a  be ORed in to.**
5e10: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
5e20: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
5e30: 74 68 65 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74  the file and not
5e40: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
5e50: 20 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 65 64   to be.** synced
5e60: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 6e 74  ..** .** The int
5e70: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
5e80: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
5e90: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
5ea0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
5eb0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
5ec0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
5ed0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
5ee0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
5ef0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
5f00: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
5f10: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
5f20: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
5f30: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5f40: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
5f50: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
5f60: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
5f70: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
5f80: 20 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 20   the lock.  .** 
5f90: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
5fa0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
5fb0: 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20  looks.** to see 
5fc0: 69 66 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  if any database 
5fd0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 74 68  connection, eith
5fe0: 65 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20 70 72  er in this.** pr
5ff0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
6000: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
6010: 69 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20 52 45  is holding an RE
6020: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
6030: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
6040: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
6050: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
6060: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
6070: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
6080: 20 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e 0a 2a   false if not..*
6090: 2a 20 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  * .** The xFileC
60a0: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
60b0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
60c0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
60d0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
60e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
60f0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
6100: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
6110: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
6120: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6130: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
6140: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
6150: 6f 70 22 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  op" argument.** 
6160: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 70  is an integer op
6170: 63 6f 64 65 2e 20 20 20 54 68 65 20 74 68 69 72  code.   The thir
6180: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  d.** argument is
6190: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
61a0: 65 72 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  er which is inte
61b0: 6e 64 65 64 20 74 6f 20 62 65 20 61 20 70 6f 69  nded to be a poi
61c0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74 72  nter.** to a str
61d0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
61e0: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
61f0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
6200: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
6210: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
6220: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
6230: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
6240: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6250: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6260: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6270: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6280: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6290: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
62a0: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
62b0: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
62c0: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
62d0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
62e0: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
62f0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6300: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6310: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6320: 73 65 72 76 65 73 20 6f 70 63 6f 64 65 73 20 6c  serves opcodes l
6330: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
6340: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 20 0a 2a   its own use. .*
6350: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
6360: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
6370: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
6380: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
6390: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
63a0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
63b0: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
63c0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
63d0: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
63e0: 70 63 6f 64 65 73 20 0a 2a 2a 20 67 72 65 61 74  pcodes .** great
63f0: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
6400: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a  void conflicts..
6410: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
6420: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
6430: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
6440: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
6450: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
6460: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
6470: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
6480: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
6490: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
64a0: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
64b0: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
64c0: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
64d0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
64e0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
64f0: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
6500: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
6510: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
6520: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
6530: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
6540: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
6550: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
6560: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6570: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
6580: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6590: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
65a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
65b0: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
65c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
65d0: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
65e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
65f0: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
6600: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6610: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
6620: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6630: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
6640: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6650: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
6660: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6670: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
6680: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6690: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
66a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
66b0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
66c0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
66d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66e0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
66f0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6700: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6710: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6720: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6730: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6740: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
6750: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
6760: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6770: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6780: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
6790: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
67a0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
67b0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
67c0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
67d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
67e0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
67f0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6800: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6810: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6820: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6830: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6840: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
6850: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
6860: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6870: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6880: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
6890: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
68a0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
68b0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
68c0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
68d0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
68e0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
68f0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6900: 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  te()..*/.typedef
6910: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6920: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
6930: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
6940: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
6950: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
6960: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
6970: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
6980: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
6990: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
69a0: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
69b0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
69c0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
69d0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
69e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
69f0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
6a00: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
6a10: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
6a20: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
6a30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
6a40: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
6a50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
6a60: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6a70: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
6a80: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
6a90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
6aa0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
6ab0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
6ac0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
6ad0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
6ae0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
6af0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
6b00: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
6b10: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
6b20: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
6b30: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
6b40: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
6b50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
6b60: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
6b70: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
6b80: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
6b90: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
6ba0: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
6bb0: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
6bc0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64  _file*);.  /* Ad
6bd0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
6be0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
6bf0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
6c00: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
6c10: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
6c20: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
6c30: 63 6f 64 65 73 20 7b 46 31 31 33 31 30 7d 0a 2a  codes {F11310}.*
6c40: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
6c50: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
6c60: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
6c70: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
6c80: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
6c90: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6ca0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 74  ds] object and t
6cb0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
6cc0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
6cd0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
6ce0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
6cf0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
6d00: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
6d10: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
6d20: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
6d30: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
6d40: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
6d50: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
6d60: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
6d70: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
6d80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6d90: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
6da0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
6db0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6dc0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
6dd0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
6de0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6df0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
6e00: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
6e10: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
6e20: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
6e30: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
6e40: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
6e50: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
6e60: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
6e70: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
6e80: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
6e90: 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ned..*/.#define 
6ea0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
6eb0: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a  KSTATE        1.
6ec0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6ed0: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 46   Mutex Handle {F
6ee0: 31 37 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  17110}.**.** The
6ef0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
6f00: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
6f10: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
6f20: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
6f30: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
6f40: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
6f50: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
6f60: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
6f70: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
6f80: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
6f90: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6fa0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
6fb0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
6fc0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
6fd0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
6fe0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
6ff0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
7000: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
7010: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
7020: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7030: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
7040: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
7050: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7060: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
7070: 65 63 74 20 7b 46 31 31 31 34 30 7d 0a 2a 2a 0a  ect {F11140}.**.
7080: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
7090: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
70a0: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
70b0: 61 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a  ace between the.
70c0: 2a 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  ** SQLite core a
70d0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
70e0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
70f0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
7100: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
7110: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
7120: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
7130: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a  file system"..**
7140: 0a 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e  .** The iVersion
7150: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
7160: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
7170: 20 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74 75   larger for futu
7180: 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
7190: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
71a0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
71b0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
71c0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
71d0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
71e0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
71f0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
7200: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
7210: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7220: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
7230: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
7240: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
7250: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
7260: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
7270: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
7280: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
7290: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
72a0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
72b0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
72c0: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
72d0: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
72e0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
72f0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
7300: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
7310: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
7320: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
7330: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
7340: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
7350: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
7360: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
7370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
7380: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
7390: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
73a0: 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  e list..**.** Th
73b0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
73c0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
73d0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
73e0: 66 73 20 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  fs .** structure
73f0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
7400: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
7410: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
7420: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
7430: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
7440: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
7450: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
7460: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
7470: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
7480: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
7490: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
74a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
74b0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
74c0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
74d0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
74e0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
74f0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
7500: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
7510: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
7520: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
7530: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
7540: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
7550: 20 7b 46 31 31 31 34 31 7d 20 53 51 4c 69 74 65   {F11141} SQLite
7560: 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20   will guarantee 
7570: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
7580: 6d 65 20 73 74 72 69 6e 67 20 70 61 73 73 65 64  me string passed
7590: 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20 69   to.** xOpen() i
75a0: 73 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61 6d  s a full pathnam
75b0: 65 20 61 73 20 67 65 6e 65 72 61 74 65 64 20 62  e as generated b
75c0: 79 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  y xFullPathname(
75d0: 29 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74 68  ) and.** that th
75e0: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
75f0: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
7600: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
7610: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
7620: 2e 20 20 7b 45 4e 44 7d 20 53 6f 20 74 68 65 20  .  {END} So the 
7630: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
7640: 61 6e 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  an store a point
7650: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
7660: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
7670: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
7680: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
7690: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a  ome reason..**.*
76a0: 2a 20 7b 46 31 31 31 34 32 7d 20 54 68 65 20 66  * {F11142} The f
76b0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
76c0: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
76d0: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
76e0: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
76f0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
7700: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
7710: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
7720: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
7730: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
7740: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
7750: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
7760: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
7770: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
7780: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
7790: 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44 7d 0a  _CREATE]. {END}.
77a0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
77b0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
77c0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
77d0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
77e0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
77f0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
7800: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
7810: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
7820: 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20 0a   be.** set..** .
7830: 2a 2a 20 7b 46 31 31 31 34 33 7d 20 53 51 4c 69  ** {F11143} SQLi
7840: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
7850: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
7860: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
7870: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
7880: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
7890: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
78a0: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a 2a 2a  g opened:.** .**
78b0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
78c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
78d0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
78e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
78f0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
7900: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
7910: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
7920: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
7930: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
7940: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7950: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
7960: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
7970: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
7980: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7990: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
79a0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  OURNAL].** </ul>
79b0: 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
79c0: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
79d0: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
79e0: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
79f0: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
7a00: 6e 67 65 73 20 74 68 65 20 77 61 79 20 69 74 20  nges the way it 
7a10: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
7a20: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
7a30: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
7a40: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
7a50: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
7a60: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
7a70: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
7a80: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
7a90: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
7aa0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
7ab0: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
7ac0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
7ad0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
7ae0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
7af0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
7b00: 6c 64 20 72 65 74 75 72 6e 20 0a 2a 2a 20 53 51  ld return .** SQ
7b10: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
7b20: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
7b30: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
7b40: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
7b50: 73 65 20 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  se .** file will
7b60: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
7b70: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
7b80: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
7b90: 6e 20 61 20 72 61 6e 64 6f 6d 20 0a 2a 2a 20 6f  n a random .** o
7ba0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
7bb0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
7bc0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
7bd0: 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  * .** SQLite mig
7be0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
7bf0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
7c00: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
7c10: 70 65 6e 0a 2a 2a 20 6d 65 74 68 6f 64 3a 0a 2a  pen.** method:.*
7c20: 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  * .** <ul>.** <l
7c30: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
7c40: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
7c50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
7c60: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
7c70: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 7b  * </ul>.** .** {
7c80: 46 31 31 31 34 35 7d 20 54 68 65 20 5b 53 51 4c  F11145} The [SQL
7c90: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
7ca0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
7cb0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
7cc0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
7cd0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
7ce0: 65 64 2e 20 20 7b 46 31 31 31 34 36 7d 20 54 68  ed.  {F11146} Th
7cf0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
7d00: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
7d10: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
7d20: 20 54 45 4d 50 20 20 64 61 74 61 62 61 73 65 73   TEMP  databases
7d30: 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66  , journals and f
7d40: 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 20  or subjournals. 
7d50: 0a 2a 2a 20 7b 46 31 31 31 34 37 7d 20 54 68 65  .** {F11147} The
7d60: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
7d70: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65  CLUSIVE] flag me
7d80: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
7d90: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a  uld be opened.**
7da0: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
7db0: 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61  ccess.  This fla
7dc0: 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c  g is set for all
7dd0: 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a   files except.**
7de0: 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61   for the main da
7df0: 74 61 62 61 73 65 20 66 69 6c 65 2e 20 7b 45 4e  tabase file. {EN
7e00: 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34  D}.** .** {F1114
7e10: 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  8} At least szOs
7e20: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
7e30: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
7e40: 65 64 20 62 79 20 53 51 4c 69 74 65 20 0a 2a 2a  ed by SQLite .**
7e50: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
7e60: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
7e70: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
7e80: 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 61   the third .** a
7e90: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
7ea0: 2e 20 20 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f  .  {END}  The xO
7eb0: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
7ec0: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
7ed0: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
7ee0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
7ef0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
7f00: 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 39  ..** .** {F11149
7f10: 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  } The flags argu
7f20: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
7f30: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
7f40: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 20  _ACCESS_EXISTS] 
7f50: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
7f60: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
7f70: 20 61 20 66 69 6c 65 2c 0a 2a 2a 20 6f 72 20 5b   a file,.** or [
7f80: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
7f90: 41 44 57 52 49 54 45 5d 20 74 6f 20 74 65 73 74  ADWRITE] to test
7fa0: 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61 20   to see.** if a 
7fb0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
7fc0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
7fd0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
7fe0: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
7ff0: 74 20 74 6f 20 73 65 65 20 69 66 20 61 20 66 69  t to see if a fi
8000: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
8010: 65 61 64 61 62 6c 65 2e 20 20 7b 45 4e 44 7d 20  eadable.  {END} 
8020: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
8030: 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e  a .** directory.
8040: 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 35 30 7d  .** .** {F11150}
8050: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
8060: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
8070: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
8080: 2b 31 20 62 79 74 65 73 20 66 6f 72 0a 2a 2a 20  +1 bytes for.** 
8090: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
80a0: 72 73 20 66 6f 72 20 78 47 65 74 54 65 6d 70 6e  rs for xGetTempn
80b0: 61 6d 65 20 61 6e 64 20 78 46 75 6c 6c 50 61 74  ame and xFullPat
80c0: 68 6e 61 6d 65 2e 20 7b 46 31 31 31 35 31 7d 20  hname. {F11151} 
80d0: 54 68 65 20 65 78 61 63 74 0a 2a 2a 20 73 69 7a  The exact.** siz
80e0: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
80f0: 62 75 66 66 65 72 20 69 73 20 61 6c 73 6f 20 70  buffer is also p
8100: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
8110: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 0a 2a 2a  eter to both .**
8120: 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20   methods. {END} 
8130: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
8140: 66 66 65 72 20 69 73 20 6e 6f 74 20 6c 61 72 67  ffer is not larg
8150: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
8160: 45 5f 43 41 4e 54 4f 50 45 4e 5d 0a 2a 2a 20 73  E_CANTOPEN].** s
8170: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
8180: 64 2e 20 41 73 20 74 68 69 73 20 69 73 20 68 61  d. As this is ha
8190: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
81a0: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
81b0: 2c 0a 2a 2a 20 76 66 73 20 69 6d 70 6c 65 6d 65  ,.** vfs impleme
81c0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
81d0: 65 6e 64 65 61 76 6f 72 20 74 6f 20 70 72 65 76  endeavor to prev
81e0: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
81f0: 69 6e 67 20 0a 2a 2a 20 6d 78 50 61 74 68 6e 61  ing .** mxPathna
8200: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
8210: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
8220: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61  ..** .** The xRa
8230: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
8240: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  ep(), and xCurre
8250: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61  ntTime() interfa
8260: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73  ces.** are not s
8270: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
8280: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
8290: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
82a0: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
82b0: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
82c0: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
82d0: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
82e0: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
82f0: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
8300: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
8310: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
8320: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
8330: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
8340: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
8350: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
8360: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
8370: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
8380: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c 65  ed.  The.** xSle
8390: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
83a0: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
83b0: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
83c0: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
83d0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
83e0: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
83f0: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
8400: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
8410: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
8420: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
8430: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
8440: 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a  and.** time..*/.
8450: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8460: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
8470: 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73  e3_vfs;.struct s
8480: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
8490: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
84a0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
84b0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
84c0: 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f  ber */.  int szO
84d0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
84e0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
84f0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
8500: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
8510: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
8520: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
8530: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
8540: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
8550: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
8560: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
8570: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
8580: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
8590: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
85a0: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
85b0: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
85c0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
85d0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
85e0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
85f0: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
8600: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
8610: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8620: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
8630: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
8640: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
8650: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
8660: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
8670: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
8680: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
8690: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
86a0: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
86b0: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
86c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
86d0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
86e0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
86f0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8700: 2a 78 47 65 74 54 65 6d 70 6e 61 6d 65 29 28 73  *xGetTempname)(s
8710: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
8720: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
8730: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
8740: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
8750: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
8760: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
8770: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
8780: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
8790: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
87a0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
87b0: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
87c0: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
87d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
87e0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
87f0: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a  rrMsg);.  void *
8800: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
8810: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
8820: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
8830: 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  l);.  void (*xDl
8840: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
8850: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
8860: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
8870: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8880: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
8890: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
88a0: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
88b0: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
88c0: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
88d0: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
88e0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
88f0: 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20  ble*);.  /* New 
8900: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
8910: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
8920: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
8930: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
8940: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
8950: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
8960: 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a   happens. */.};.
8970: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8980: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
8990: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
89a0: 64 20 7b 46 31 31 31 39 30 7d 0a 2a 2a 0a 2a 2a  d {F11190}.**.**
89b0: 20 7b 46 31 31 31 39 31 7d 20 54 68 65 73 65 20   {F11191} These 
89c0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
89d0: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
89e0: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
89f0: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
8a00: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
8a10: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
8a20: 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20  ] object. {END} 
8a30: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
8a40: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
8a50: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
8a60: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
8a70: 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  s.** looking for
8a80: 2e 20 20 7b 46 31 31 31 39 32 7d 20 57 69 74 68  .  {F11192} With
8a90: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
8aa0: 45 58 49 53 54 53 5d 2c 20 74 68 65 20 78 41 63  EXISTS], the xAc
8ab0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
8ac0: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f 20  imply checks to 
8ad0: 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20  see if the file 
8ae0: 65 78 69 73 74 73 2e 20 7b 46 31 31 31 39 33 7d  exists. {F11193}
8af0: 20 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   With.** SQLITE_
8b00: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
8b10: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
8b20: 74 68 6f 64 20 63 68 65 63 6b 73 20 74 6f 20 73  thod checks to s
8b30: 65 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c  ee.** if the fil
8b40: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  e is both readab
8b50: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e  le and writable.
8b60: 20 20 7b 46 31 31 31 39 34 7d 20 57 69 74 68 0a    {F11194} With.
8b70: 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ** SQLITE_ACCESS
8b80: 5f 52 45 41 44 20 74 68 65 20 78 41 63 63 65 73  _READ the xAcces
8b90: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
8ba0: 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65  ks to see if the
8bb0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8bc0: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
8bd0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
8be0: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
8bf0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8c00: 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e  ADWRITE 1.#defin
8c10: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
8c20: 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a  READ      2../*.
8c30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
8c40: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
8c50: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
8c60: 6f 64 65 73 20 7b 46 31 32 32 30 30 7d 0a 2a 2a  odes {F12200}.**
8c70: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
8c80: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
8c90: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
8ca0: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
8cb0: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  les the.** [SQLI
8cc0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
8cd0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
8ce0: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
8cf0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 54 68 65  f SQLite..** The
8d00: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
8d10: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
8d20: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
8d30: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
8d40: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
8d50: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
8d60: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31 7d  :.**.** {F12201}
8d70: 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62   Each new [datab
8d80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
8d90: 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65 20 0a  shall have the .
8da0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
8db0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
8dc0: 65 73 5d 20 66 65 61 74 75 72 65 0a 2a 2a 20 20  es] feature.**  
8dd0: 20 20 20 20 20 20 20 20 64 69 73 61 62 6c 65 64          disabled
8de0: 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
8df0: 2a 2a 20 7b 46 31 32 32 30 32 7d 20 54 68 65 20  ** {F12202} The 
8e00: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
8e10: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44  d_result_codes(D
8e20: 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ,F)] interface s
8e30: 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20  hall enable.**  
8e40: 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65          [extende
8e50: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
8e60: 66 6f 72 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  for the .**     
8e70: 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
8e80: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 66 20  onnection] D if 
8e90: 74 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 0a  the F parameter.
8ea0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 74  **          is t
8eb0: 72 75 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20  rue, or disable 
8ec0: 74 68 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c  them if F is fal
8ed0: 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  se..*/.int sqlit
8ee0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
8ef0: 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
8f00: 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
8f10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8f20: 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
8f30: 64 20 7b 46 31 32 32 32 30 7d 0a 2a 2a 0a 2a 2a  d {F12220}.**.**
8f40: 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61   Each entry in a
8f50: 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68  n SQLite table h
8f60: 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
8f70: 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
8f80: 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
8f90: 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65  the "rowid". The
8fa0: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
8fb0: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
8fc0: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
8fd0: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
8fe0: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
8ff0: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
9000: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
9010: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
9020: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
9030: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49  lared columns. I
9040: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
9050: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
9060: 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d  ype INTEGER PRIM
9070: 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61  ARY KEY then tha
9080: 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
9090: 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
90a0: 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
90b0: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
90c0: 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64  eturns the rowid
90d0: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
90e0: 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ent.** successfu
90f0: 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68  l INSERT into th
9100: 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
9110: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
9120: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 77 6e  nection.** shown
9130: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
9140: 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73  gument.  If no s
9150: 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74  uccessful insert
9160: 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
9170: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 69 73 20  ccurred on this 
9180: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9190: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
91a0: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  urned..**.** If 
91b0: 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73  an INSERT occurs
91c0: 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
91d0: 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69  r, then the rowi
91e0: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65  d of the.** inse
91f0: 72 74 65 64 20 72 6f 77 20 69 73 20 72 65 74 75  rted row is retu
9200: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
9210: 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20  tine as long as 
9220: 74 68 65 20 74 72 69 67 67 65 72 0a 2a 2a 20 69  the trigger.** i
9230: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 42 75 74 20  s running.  But 
9240: 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
9250: 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
9260: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
9270: 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
9280: 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ne reverts to th
9290: 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
92a0: 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
92b0: 0a 2a 2a 20 74 72 69 67 67 65 72 20 66 69 72 65  .** trigger fire
92c0: 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45  d..**.** An INSE
92d0: 52 54 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  RT that fails du
92e0: 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
92f0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
9300: 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
9310: 75 6c 20 69 6e 73 65 72 74 20 61 6e 64 20 64 6f  ul insert and do
9320: 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
9330: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
9340: 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
9350: 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52  ine.  Thus INSER
9360: 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
9370: 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
9380: 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
9390: 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
93a0: 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
93b0: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
93c0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
93d0: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
93e0: 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
93f0: 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e  ion fails.  When
9400: 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
9410: 43 45 20 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  CE .** encounter
9420: 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
9430: 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
9440: 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
9450: 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
9460: 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
9470: 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
9480: 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
9490: 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
94a0: 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
94b0: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
94c0: 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
94d0: 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
94e0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
94f0: 20 69 6e 74 65 72 66 61 63 65 2e 20 0a 2a 2a 0a   interface. .**.
9500: 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f  ** For the purpo
9510: 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
9520: 69 6e 65 2c 20 61 6e 20 69 6e 73 65 72 74 20 69  ine, an insert i
9530: 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
9540: 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
9550: 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
9560: 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
9570: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ed back..**.** I
9580: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
9590: 20 7b 46 31 32 32 32 31 7d 20 54 68 65 20 5b 73   {F12221} The [s
95a0: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
95b0: 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63  rt_rowid()] func
95c0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
95d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77  .**          row
95e0: 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  id of the most r
95f0: 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
9600: 20 69 6e 73 65 72 74 20 64 6f 6e 65 0a 2a 2a 20   insert done.** 
9610: 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
9620: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
9630: 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 77 69 74  nnection and wit
9640: 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
9650: 20 20 20 20 20 20 20 20 20 6f 72 20 68 69 67 68           or high
9660: 65 72 20 6c 65 76 65 6c 20 74 72 69 67 67 65 72  er level trigger
9670: 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72   context, or zer
9680: 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65 0a  o if there have.
9690: 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 65 6e  **          been
96a0: 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69   no qualifying i
96b0: 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nserts..**.** {F
96c0: 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69  12223} The [sqli
96d0: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
96e0: 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f  rowid()] functio
96f0: 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  n returns.**    
9700: 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65        same value
9710: 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
9720: 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  m the same trigg
9730: 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20  er context.**   
9740: 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65         immediate
9750: 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66  ly before and af
9760: 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a  ter a ROLLBACK..
9770: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
9780: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 33 32  S:.**.** {U12232
9790: 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  } If a separate 
97a0: 74 68 72 65 61 64 20 64 6f 65 73 20 61 20 6e 65  thread does a ne
97b0: 77 20 69 6e 73 65 72 74 20 6f 6e 20 74 68 65 20  w insert on the 
97c0: 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
97d0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
97e0: 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
97f0: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
9800: 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
9810: 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
9820: 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
9830: 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
9840: 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
9850: 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  wid,.**         
9860: 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
9870: 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
9880: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
9890: 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
98a0: 20 20 20 20 20 20 20 20 20 75 6e 70 72 65 64 69           unpredi
98b0: 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
98c0: 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
98d0: 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
98e0: 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
98f0: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77   last insert row
9900: 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  id..*/.sqlite3_i
9910: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
9920: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
9930: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
9940: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
9950: 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
9960: 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31  ows Modified {F1
9970: 32 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2240}.**.** This
9980: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
9990: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
99a0: 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
99b0: 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
99c0: 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
99d0: 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
99e0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
99f0: 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
9a00: 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
9a10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
9a20: 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
9a30: 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 4f  st parameter.  O
9a40: 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  nly.** changes t
9a50: 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79  hat are directly
9a60: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
9a70: 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
9a80: 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73  , or.** DELETE s
9a90: 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
9aa0: 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
9ab0: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
9ac0: 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61  by.** triggers a
9ad0: 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
9ae0: 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
9af0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
9b00: 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f  ] function.** to
9b10: 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20   find the total 
9b20: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
9b30: 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  s including chan
9b40: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
9b50: 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  iggers..**.** A 
9b60: 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20  "row change" is 
9b70: 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69  a change to a si
9b80: 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69  ngle row of a si
9b90: 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61  ngle table.** ca
9ba0: 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52  used by an INSER
9bb0: 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50  T, DELETE, or UP
9bc0: 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20  DATE statement. 
9bd0: 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72   Rows that.** ar
9be0: 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64  e changed as sid
9bf0: 65 20 65 66 66 65 63 74 73 20 6f 66 20 52 45 50  e effects of REP
9c00: 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
9c10: 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72  resolution,.** r
9c20: 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70  ollback, ABORT p
9c30: 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50 20  rocessing, DROP 
9c40: 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79  TABLE, or by any
9c50: 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e   other.** mechan
9c60: 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  isms do not coun
9c70: 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20  t as direct row 
9c80: 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  changes..**.** A
9c90: 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
9ca0: 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
9cb0: 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
9cc0: 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
9cd0: 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
9ce0: 70 74 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e  pt of a trigger.
9cf0: 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65    Most SQL state
9d00: 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
9d10: 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
9d20: 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
9d30: 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
9d40: 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
9d50: 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
9d60: 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
9d70: 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
9d80: 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
9d90: 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
9da0: 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
9db0: 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
9dc0: 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
9dd0: 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
9de0: 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
9df0: 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
9e00: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69  ion..**.** Calli
9e10: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
9e20: 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
9e30: 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
9e40: 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
9e50: 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
9e60: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
9e70: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
9e80: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
9e90: 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
9ea0: 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
9eb0: 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
9ec0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
9ed0: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
9ee0: 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
9ef0: 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
9f00: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53  context..**.** S
9f10: 6f 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  o when called fr
9f20: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
9f30: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
9f40: 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
9f50: 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
9f60: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
9f70: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
9f80: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
9f90: 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
9fa0: 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
9fb0: 65 76 65 6c 2e 0a 2a 2a 20 57 69 74 68 69 6e 20  evel..** Within 
9fc0: 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
9fd0: 69 67 67 65 72 2c 20 74 68 65 20 73 71 6c 69 74  igger, the sqlit
9fe0: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
9ff0: 65 72 66 61 63 65 0a 2a 2a 20 63 61 6e 20 62 65  erface.** can be
a000: 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
a010: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
a020: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
a030: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
a040: 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
a050: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
a060: 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
a070: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
a080: 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  f the same trigg
a090: 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  er..** However, 
a0a0: 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72  the number retur
a0b0: 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
a0c0: 6c 75 64 65 20 69 6e 20 63 68 61 6e 67 65 73 0a  lude in changes.
a0d0: 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
a0e0: 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
a0f0: 68 65 79 20 68 61 76 65 20 74 68 65 69 72 20 6f  hey have their o
a100: 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  wn context..**.*
a110: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
a120: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
a130: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
a140: 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  le" without.** a
a150: 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 62 79   WHERE clause by
a160: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
a170: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
a180: 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
a190: 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 74 68 61  ch.** faster tha
a1a0: 6e 20 67 6f 69 6e 67 20 74 68 72 6f 75 67 68 20  n going through 
a1b0: 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
a1c0: 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
a1d0: 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 61 62   from the.** tab
a1e0: 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66  le.)  Because of
a1f0: 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69   this optimizati
a200: 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e  on, the deletion
a210: 73 20 69 6e 0a 2a 2a 20 22 44 45 4c 45 54 45 20  s in.** "DELETE 
a220: 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20  FROM table" are 
a230: 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  not row changes 
a240: 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  and will not be 
a250: 63 6f 75 6e 74 65 64 0a 2a 2a 20 62 79 20 74 68  counted.** by th
a260: 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
a270: 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  s() or [sqlite3_
a280: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
a290: 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54   functions..** T
a2a0: 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74  o get an accurat
a2b0: 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e  e count of the n
a2c0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65  umber of rows de
a2d0: 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44  leted, use.** "D
a2e0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
a2f0: 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61   WHERE 1" instea
a300: 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
a310: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  NTS:.**.** {F122
a320: 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
a330: 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
a340: 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72  tion shall retur
a350: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  n the number of.
a360: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 20  **          row 
a370: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
a380: 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
a390: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
a3a0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
a3b0: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
a3c0: 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  t on the same da
a3d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a3e0: 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  n and.**        
a3f0: 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d    within the sam
a400: 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 69 67  e or higher trig
a410: 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20  ger context, or 
a420: 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61  zero if there ha
a430: 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ve.**          n
a440: 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c  ot been any qual
a450: 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67  ifying row chang
a460: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34  es..**.** {F1224
a470: 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66  3} Statements of
a480: 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54   the form "DELET
a490: 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65  E FROM tablename
a4a0: 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20  " with no.**    
a4b0: 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75        WHERE clau
a4c0: 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73  se shall cause s
a4d0: 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
a4e0: 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  to .**          
a4f0: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
a500: 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65  ()] to return ze
a510: 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ro, regardless o
a520: 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
a530: 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73    number of rows
a540: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74   originally in t
a550: 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  he table..**.** 
a560: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
a570: 2a 2a 20 7b 55 31 32 32 35 32 7d 20 49 66 20 61  ** {U12252} If a
a580: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
a590: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
a5a0: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
a5b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
a5c0: 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65  *          while
a5d0: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
a5e0: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
a5f0: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
a600: 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20  eturned.**      
a610: 20 20 20 20 69 73 20 75 6e 70 72 65 64 69 63 74      is unpredict
a620: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
a630: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
a640: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
a650: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
a660: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
a670: 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
a680: 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32 36   Modified {F1226
a690: 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  0}.***.** This f
a6a0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
a6b0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
a6c0: 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
a6d0: 0a 2a 2a 20 62 79 20 49 4e 53 45 52 54 2c 20 55  .** by INSERT, U
a6e0: 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
a6f0: 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
a700: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61   the database ha
a710: 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f 70 65 6e  ndle.** was open
a720: 65 64 2e 20 20 54 68 65 20 63 6f 75 6e 74 20 69  ed.  The count i
a730: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
a740: 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69  ges from all tri
a750: 67 67 65 72 0a 2a 2a 20 63 6f 6e 74 65 78 74 73  gger.** contexts
a760: 2e 20 20 42 75 74 20 74 68 65 20 63 6f 75 6e 74  .  But the count
a770: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
a780: 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
a790: 6f 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 52  o.** implement R
a7a0: 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
a7b0: 74 73 2c 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  ts, do rollbacks
a7c0: 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
a7d0: 73 69 6e 67 2c 0a 2a 2a 20 6f 72 20 44 52 4f 50  sing,.** or DROP
a7e0: 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e   table processin
a7f0: 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65  g..** The change
a800: 73 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64  s.** are counted
a810: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
a820: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
a830: 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
a840: 70 6c 65 74 65 64 20 0a 2a 2a 20 28 77 68 65 6e  pleted .** (when
a850: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
a860: 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20  andle is passed 
a870: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
a880: 74 28 29 5d 20 6f 72 20 0a 2a 2a 20 5b 73 71 6c  t()] or .** [sql
a890: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
a8a0: 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  )..**.** SQLite 
a8b0: 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63  implements the c
a8c0: 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46  ommand "DELETE F
a8d0: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f  ROM table" witho
a8e0: 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20 63 6c  ut.** a WHERE cl
a8f0: 61 75 73 65 20 62 79 20 64 72 6f 70 70 69 6e 67  ause by dropping
a900: 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20   and recreating 
a910: 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69  the table.  (Thi
a920: 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61 73  s is much.** fas
a930: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a  ter than going.*
a940: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65  * through and de
a950: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61  leting individua
a960: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20  l elements from 
a970: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63  the table.)  Bec
a980: 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20  ause of.** this 
a990: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
a9a0: 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66  e change count f
a9b0: 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  or "DELETE FROM 
a9c0: 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a  table" will be.*
a9d0: 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73  * zero regardles
a9e0: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  s of the number 
a9f0: 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74  of elements that
aa00: 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79   were originally
aa10: 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65   in the.** table
aa20: 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75  . To get an accu
aa30: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68  rate count of th
aa40: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
aa50: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a   deleted, use.**
aa60: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
aa70: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73  ble WHERE 1" ins
aa80: 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tead..**.** See 
aa90: 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
aaa0: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
aab0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  erface..**.** IN
aac0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a  VARIANTS:.** .**
aad0: 20 7b 46 31 32 32 36 31 7d 20 54 68 65 20 5b 73   {F12261} The [s
aae0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
aaf0: 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73 20  nges()] returns 
ab00: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
ab10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
ab20: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
ab30: 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50  ed by INSERT, UP
ab40: 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c  DATE, and/or DEL
ab50: 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ETE.**          
ab60: 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68  statements on th
ab70: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
ab80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e   connection], in
ab90: 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20 20   any.**         
aba0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
abb0: 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  , since the data
abc0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
abd0: 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  was.**          
abe0: 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  created..**.** {
abf0: 46 31 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e  F12263} Statemen
ac00: 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ts of the form "
ac10: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
ac20: 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a  ename" with no.*
ac30: 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45  *          WHERE
ac40: 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f   clause shall no
ac50: 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
ac60: 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20  ue returned.**  
ac70: 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
ac80: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
ac90: 73 28 29 5d 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  s()].**.** LIMIT
aca0: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
acb0: 31 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61  12264} If a sepa
acc0: 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
acd0: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
ace0: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
acf0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
ad00: 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c        while [sql
ad10: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
ad20: 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
ad30: 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
ad40: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
ad50: 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
ad60: 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
ad70: 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
ad80: 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
ad90: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
ada0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
adb0: 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
adc0: 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
add0: 72 79 20 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a  ry {F12270}.**.*
ade0: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
adf0: 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
ae00: 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
ae10: 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
ae20: 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
ae30: 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
ae40: 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
ae50: 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
ae60: 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
ae70: 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
ae80: 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
ae90: 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
aea0: 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
aeb0: 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
aec0: 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
aed0: 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
aee0: 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
aef0: 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tely..**.** It i
af00: 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
af10: 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
af20: 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
af30: 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
af40: 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
af50: 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
af60: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
af70: 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
af80: 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
af90: 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
afa0: 74 69 6e 65 20 77 69 74 68 20 61 20 64 61 74 61  tine with a data
afb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
afc0: 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
afd0: 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
afe0: 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
aff0: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
b000: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
b010: 20 53 51 4c 20 69 73 20 76 65 72 79 20 6e 65 61   SQL is very nea
b020: 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
b030: 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 73 71  the time when sq
b040: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
b050: 29 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 2c 20  ).** is called, 
b060: 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
b070: 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
b080: 75 6e 69 74 79 20 74 6f 20 62 65 20 69 6e 74 65  unity to be inte
b090: 72 72 75 70 74 65 64 2e 0a 2a 2a 20 49 74 20 6d  rrupted..** It m
b0a0: 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
b0b0: 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 20   completion..** 
b0c0: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
b0d0: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
b0e0: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
b0f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
b100: 52 52 55 50 54 5d 2e 20 20 49 66 20 74 68 65 20  RRUPT].  If the 
b110: 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
b120: 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 0a  operation is an.
b130: 2a 2a 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ** INSERT, UPDAT
b140: 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 74 68 61  E, or DELETE tha
b150: 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
b160: 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
b170: 69 6f 6e 2c 20 0a 2a 2a 20 74 68 65 6e 20 74 68  ion, .** then th
b180: 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
b190: 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72 6f 6c  tion will be rol
b1a0: 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
b1b0: 69 63 61 6c 6c 79 2e 0a 2a 2a 20 41 20 63 61 6c  ically..** A cal
b1c0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
b1d0: 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20  errupt() has no 
b1e0: 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
b1f0: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
b200: 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
b210: 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  er sqlite3_inter
b220: 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
b230: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
b240: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 31 7d  :.**.** {F12271}
b250: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e   The [sqlite3_in
b260: 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72  terrupt()] inter
b270: 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20  face will force 
b280: 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20  all running.**  
b290: 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74          SQL stat
b2a0: 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
b2b0: 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
b2c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b2d0: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
b2e0: 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20 70 72  to halt after pr
b2f0: 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74  ocessing at most
b300: 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   one additional 
b310: 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  row of.**       
b320: 20 20 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b     data..**.** {
b330: 46 31 32 32 37 32 7d 20 41 6e 79 20 53 51 4c 20  F12272} Any SQL 
b340: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69  statement that i
b350: 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 62 79  s interrupted by
b360: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
b370: 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  upt()].**       
b380: 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b     will return [
b390: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
b3a0: 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  ]..**.** LIMITAT
b3b0: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
b3c0: 32 37 39 7d 20 49 66 20 74 68 65 20 64 61 74 61  279} If the data
b3d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
b3e0: 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
b3f0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
b400: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
b410: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
b420: 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
b430: 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
b440: 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
b450: 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
b460: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
b470: 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
b480: 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
b490: 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 46  t Is Complete {F
b4a0: 31 30 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10510}.**.** The
b4b0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
b4c0: 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61  useful for comma
b4d0: 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
b4e0: 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
b4f0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
b500: 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
b510: 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65  s to form comple
b520: 74 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65  te a SQL stateme
b530: 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
b540: 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
b550: 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
b560: 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
b570: 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
b580: 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73  r parsing.  Thes
b590: 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
b5a0: 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 69 6e  n true if the in
b5b0: 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
b5c0: 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
b5d0: 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
b5e0: 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65  ment.  A stateme
b5f0: 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
b600: 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
b610: 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
b620: 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
b630: 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72   and is not a fr
b640: 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43  agment of a.** C
b650: 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
b660: 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f  atement.  Semico
b670: 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
b680: 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
b690: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
b6a0: 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
b6b0: 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
b6c0: 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
b6d0: 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
b6e0: 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
b6f0: 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
b700: 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
b710: 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
b720: 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
b730: 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
b740: 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
b750: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
b760: 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
b770: 72 73 65 20 74 68 65 20 53 51 4c 20 61 6e 64 0a  rse the SQL and.
b780: 2a 2a 20 73 6f 20 77 69 6c 6c 20 6e 6f 74 20 64  ** so will not d
b790: 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
b7a0: 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
b7b0: 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  L..**.** INVARIA
b7c0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35  NTS:.**.** {F105
b7d0: 31 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  11} The sqlite3_
b7e0: 63 6f 6d 70 6c 65 74 65 28 29 20 61 6e 64 20 73  complete() and s
b7f0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
b800: 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
b810: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
b820: 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
b830: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
b840: 74 68 65 20 6c 61 73 74 0a 2a 2a 20 20 20 20 20  the last.**     
b850: 20 20 20 20 20 6e 6f 6e 2d 77 68 69 74 65 73 70       non-whitesp
b860: 61 63 65 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65  ace token in the
b870: 69 72 20 69 6e 70 75 74 20 69 73 20 61 20 73 65  ir input is a se
b880: 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 0a 2a 2a 20  micolon that.** 
b890: 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20           is not 
b8a0: 69 6e 20 62 65 74 77 65 65 6e 20 74 68 65 20 42  in between the B
b8b0: 45 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20  EGIN and END of 
b8c0: 61 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  a CREATE TRIGGER
b8d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
b8e0: 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49  tement..**.** LI
b8f0: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
b900: 20 7b 55 31 30 35 31 32 7d 20 54 68 65 20 69 6e   {U10512} The in
b910: 70 75 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  put to sqlite3_c
b920: 6f 6d 70 6c 65 74 65 28 29 20 6d 75 73 74 20 62  omplete() must b
b930: 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
b940: 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
b950: 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
b960: 0a 2a 2a 20 7b 55 31 30 35 31 33 7d 20 54 68 65  .** {U10513} The
b970: 20 69 6e 70 75 74 20 74 6f 20 73 71 6c 69 74 65   input to sqlite
b980: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 6d  3_complete16() m
b990: 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
b9a0: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
b9b0: 20 20 20 20 20 55 54 46 2d 31 36 20 73 74 72 69       UTF-16 stri
b9c0: 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
b9d0: 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
b9e0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
b9f0: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
ba00: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
ba10: 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
ba20: 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
ba30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
ba40: 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
ba50: 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
ba60: 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b 46  E_BUSY Errors {F
ba70: 31 32 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  12310}.**.** Thi
ba80: 73 20 72 6f 75 74 69 6e 65 20 69 64 65 6e 74 69  s routine identi
ba90: 66 69 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  fies a callback 
baa0: 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
bab0: 67 68 74 20 62 65 0a 2a 2a 20 69 6e 76 6f 6b 65  ght be.** invoke
bac0: 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 61 74  d whenever an at
bad0: 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
bae0: 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
baf0: 20 74 61 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20   table .** that 
bb00: 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6f  another thread o
bb10: 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
bb20: 63 6b 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cked..** If the 
bb30: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
bb40: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
bb50: 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
bb60: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
bb70: 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
bb80: 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
bb90: 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
bba0: 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ing the lock..**
bbb0: 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
bbc0: 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c  lback is not NUL
bbd0: 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63  L, then the.** c
bbe0: 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20  allback will be 
bbf0: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
bc00: 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
bc10: 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65  .** first argume
bc20: 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65  nt to the handle
bc30: 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
bc40: 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
bc50: 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
bc60: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
bc70: 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  to this routine.
bc80: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
bc90: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
bca0: 68 61 6e 64 6c 65 72 20 69 73 20 74 68 65 20 6e  handler is the n
bcb0: 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
bcc0: 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
bcd0: 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
bce0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69   invoked for thi
bcf0: 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  s locking event.
bd00: 20 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73     If the.** bus
bd10: 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
bd20: 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
bd30: 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
bd40: 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
bd50: 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
bd60: 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
bd70: 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
bd80: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
bd90: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
bda0: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
bdb0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
bdc0: 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
bdd0: 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
bde0: 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
bdf0: 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
be00: 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
be10: 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
be20: 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
be30: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
be40: 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
be50: 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20 77 69  ee that.** it wi
be60: 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ll be invoked wh
be70: 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
be80: 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20   contention..** 
be90: 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
bea0: 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
beb0: 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
bec0: 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
bed0: 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63   in.** a deadloc
bee0: 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
bef0: 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
bf00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 0a  SQLITE_BUSY] or.
bf10: 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
bf20: 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
bf30: 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
bf40: 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65  e.** busy handle
bf50: 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
bf60: 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
bf70: 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
bf80: 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
bf90: 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
bfa0: 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
bfb0: 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
bfc0: 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
bfd0: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
bfe0: 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
bff0: 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
c000: 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
c010: 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
c020: 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
c030: 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
c040: 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
c050: 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
c060: 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
c070: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
c080: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
c090: 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
c0a0: 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
c0b0: 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
c0c0: 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
c0d0: 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
c0e0: 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
c0f0: 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
c100: 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
c110: 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
c120: 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
c130: 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
c140: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
c150: 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
c160: 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
c170: 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
c180: 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
c190: 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
c1a0: 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
c1b0: 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
c1c0: 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
c1d0: 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
c1e0: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
c1f0: 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
c200: 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
c210: 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
c220: 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
c230: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
c240: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
c250: 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
c260: 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
c270: 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
c280: 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
c290: 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
c2a0: 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
c2b0: 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
c2c0: 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
c2d0: 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
c2e0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
c2f0: 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
c300: 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
c310: 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
c320: 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
c330: 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
c340: 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
c350: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
c360: 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
c370: 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
c380: 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69  * readers.  If i
c390: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
c3a0: 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
c3b0: 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
c3c0: 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
c3d0: 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
c3e0: 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
c3f0: 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
c400: 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
c410: 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
c420: 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
c430: 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
c440: 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
c450: 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
c460: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
c470: 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
c480: 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
c490: 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
c4a0: 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
c4b0: 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
c4c0: 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68  he.** <a href="h
c4d0: 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65  ttp://www.sqlite
c4e0: 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f 77 69 6b  .org/cvstrac/wik
c4f0: 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
c500: 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
c510: 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
c520: 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
c530: 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
c540: 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
c550: 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
c560: 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
c570: 2a 09 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  *..** There can 
c580: 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
c590: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
c5a0: 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 20 64  fined for each d
c5b0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
c5c0: 63 74 69 6f 6e 2e 20 20 53 65 74 74 69 6e 67 20  ction.  Setting 
c5d0: 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
c5e0: 65 72 20 63 6c 65 61 72 73 20 61 6e 79 20 70 72  er clears any pr
c5f0: 65 76 69 6f 75 73 20 6f 6e 65 2e 20 0a 2a 2a 20  evious one. .** 
c600: 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
c610: 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
c620: 74 69 6d 65 6f 75 74 28 29 5d 20 77 69 6c 6c 20  timeout()] will 
c630: 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
c640: 72 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  r.** the busy ha
c650: 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ndler..**.** INV
c660: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
c670: 46 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c  F12311} The [sql
c680: 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
c690: 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  r()] function re
c6a0: 70 6c 61 63 65 73 20 74 68 65 20 62 75 73 79 20  places the busy 
c6b0: 68 61 6e 64 6c 65 72 0a 2a 2a 20 20 20 20 20 20  handler.**      
c6c0: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20      callback in 
c6d0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
c6e0: 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69  nection identifi
c6f0: 65 64 20 62 79 20 74 68 65 20 31 73 74 0a 2a 2a  ed by the 1st.**
c700: 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
c710: 74 65 72 20 77 69 74 68 20 61 20 6e 65 77 20 62  ter with a new b
c720: 75 73 79 20 68 61 6e 64 6c 65 72 20 69 64 65 6e  usy handler iden
c730: 74 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  tified by the 2n
c740: 64 20 61 6e 64 20 33 72 64 0a 2a 2a 20 20 20 20  d and 3rd.**    
c750: 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73        parameters
c760: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 32 7d  ..**.** {F12312}
c770: 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73   The default bus
c780: 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 6e 65  y handler for ne
c790: 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
c7a0: 63 74 69 6f 6e 73 20 69 73 20 4e 55 4c 4c 2e 0a  ctions is NULL..
c7b0: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 34 7d 20 57  **.** {F12314} W
c7c0: 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20  hen two or more 
c7d0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c7e0: 69 6f 6e 20 73 68 61 72 65 20 61 20 5b 73 71 6c  ion share a [sql
c7f0: 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
c800: 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f  ed_cache | commo
c810: 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20  n cache],.**    
c820: 20 20 20 20 20 20 74 68 65 20 62 75 73 79 20 68        the busy h
c830: 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64  andler for the d
c840: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c850: 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  on currently usi
c860: 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ng.**          t
c870: 68 65 20 63 61 63 68 65 20 69 73 20 69 6e 76 6f  he cache is invo
c880: 6b 65 64 20 77 68 65 6e 20 74 68 65 20 63 61 63  ked when the cac
c890: 68 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  he encounters a 
c8a0: 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  lock..**.** {F12
c8b0: 33 31 36 7d 20 49 66 20 61 20 62 75 73 79 20 68  316} If a busy h
c8c0: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
c8d0: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
c8e0: 65 6e 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a  en the SQLite.**
c8f0: 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
c900: 61 63 65 20 74 68 61 74 20 70 72 6f 76 6f 6b 65  ace that provoke
c910: 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76  d the locking ev
c920: 65 6e 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ent will return.
c930: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
c940: 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
c950: 20 7b 46 31 32 33 31 38 7d 20 53 51 4c 69 74 65   {F12318} SQLite
c960: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68   will invokes th
c970: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77  e busy handler w
c980: 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
c990: 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20  s which.**      
c9a0: 20 20 20 20 61 72 65 20 61 20 63 6f 70 79 20 6f      are a copy o
c9b0: 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73 75  f the pointer su
c9c0: 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 33 72  pplied by the 3r
c9d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
c9e0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
c9f0: 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
ca00: 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74 20  ()] and a count 
ca10: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
ca20: 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
ca30: 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f     invocations o
ca40: 66 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  f the busy handl
ca50: 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  er for the same 
ca60: 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a  locking event..*
ca70: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
ca80: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 33 31 39 7d  :.**.** {U12319}
ca90: 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
caa0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
cab0: 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
cac0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
cad0: 20 20 20 20 20 20 20 20 20 20 6f 72 20 70 72 65            or pre
cae0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
caf0: 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
cb00: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
cb10: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
cb20: 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
cb30: 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
cb40: 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
cb50: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
cb60: 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
cb70: 6f 75 74 20 7b 46 31 32 33 34 30 7d 0a 2a 2a 0a  out {F12340}.**.
cb80: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
cb90: 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
cba0: 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
cbb0: 75 73 79 20 68 61 6e 64 6c 65 72 5d 0a 2a 2a 20  usy handler].** 
cbc0: 74 68 61 74 20 73 6c 65 65 70 73 20 66 6f 72 20  that sleeps for 
cbd0: 61 20 77 68 69 6c 65 20 77 68 65 6e 20 61 0a 2a  a while when a.*
cbe0: 2a 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  * table is locke
cbf0: 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 20  d.  The handler 
cc00: 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
cc10: 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
cc20: 0a 2a 2a 20 61 74 20 6c 65 61 73 74 20 22 6d 73  .** at least "ms
cc30: 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
cc40: 66 20 73 6c 65 65 70 69 6e 67 20 68 61 76 65 20  f sleeping have 
cc50: 62 65 65 6e 20 64 6f 6e 65 2e 20 7b 46 31 32 33  been done. {F123
cc60: 34 33 7d 20 41 66 74 65 72 0a 2a 2a 20 22 6d 73  43} After.** "ms
cc70: 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
cc80: 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68 65 20  f sleeping, the 
cc90: 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
cca0: 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75 73 65  0 which.** cause
ccb0: 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
ccc0: 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b 53 51  )] to return [SQ
ccd0: 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
cce0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
ccf0: 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  KED]..**.** Call
cd00: 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
cd10: 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
cd20: 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
cd30: 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
cd40: 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
cd50: 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
cd60: 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c  ** There can onl
cd70: 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
cd80: 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
cd90: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
cda0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
cdb0: 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  on.  If another 
cdc0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 61 73  busy handler was
cdd0: 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20 28 75   defined  .** (u
cde0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
cdf0: 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
ce00: 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
ce10: 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
ce20: 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
ce30: 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
ce40: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  red..**.** INVAR
ce50: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
ce60: 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2341} The [sqlit
ce70: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
ce80: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 6f 76 65 72  )] function over
ce90: 72 69 64 65 73 20 61 6e 79 20 70 72 69 6f 72 0a  rides any prior.
cea0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
ceb0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
cec0: 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
ced0: 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
cee0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
cef0: 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65       on the same
cf00: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
cf10: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  tion..**.** {F12
cf20: 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20  343} If the 2nd 
cf30: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
cf40: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
cf50: 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68  ut()] is less th
cf60: 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  an.**          o
cf70: 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c  r equal to zero,
cf80: 20 74 68 65 6e 20 74 68 65 20 62 75 73 79 20 68   then the busy h
cf90: 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
cfa0: 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20  d so that.**    
cfb0: 20 20 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71        all subseq
cfc0: 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65  uent locking eve
cfd0: 6e 74 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  nts immediately 
cfe0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
cff0: 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  USY]..**.** {F12
d000: 33 34 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20  344} If the 2nd 
d010: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
d020: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
d030: 75 74 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74  ut()] is a posit
d040: 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
d050: 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61  number N, then a
d060: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
d070: 20 73 65 74 20 74 68 61 74 20 72 65 70 65 61 74   set that repeat
d080: 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20  edly calls.**   
d090: 20 20 20 20 20 20 20 74 68 65 20 78 53 6c 65 65         the xSlee
d0a0: 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74 68  p() method in th
d0b0: 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20  e VFS interface 
d0c0: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
d0d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 63  .**          loc
d0e0: 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74 69  k clears or unti
d0f0: 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76 65  l the cumulative
d100: 20 73 6c 65 65 70 20 74 69 6d 65 20 72 65 70 6f   sleep time repo
d110: 72 74 65 64 20 62 61 63 6b 0a 2a 2a 20 20 20 20  rted back.**    
d120: 20 20 20 20 20 20 62 79 20 78 53 6c 65 65 70 28        by xSleep(
d130: 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c  ) exceeds N mill
d140: 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74  iseconds..*/.int
d150: 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
d160: 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
d170: 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
d180: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
d190: 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
d1a0: 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
d1b0: 65 73 20 7b 46 31 32 33 37 30 7d 0a 2a 2a 0a 2a  es {F12370}.**.*
d1c0: 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
d1d0: 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
d1e0: 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
d1f0: 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
d200: 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
d210: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
d220: 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
d230: 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
d240: 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
d250: 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
d260: 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
d270: 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
d280: 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
d290: 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
d2a0: 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
d2b0: 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
d2c0: 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
d2d0: 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
d2e0: 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
d2f0: 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
d300: 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
d310: 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
d320: 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
d330: 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
d340: 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
d350: 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
d360: 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
d370: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
d380: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
d390: 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
d3a0: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
d3b0: 38 20 73 74 72 69 6e 67 73 2e 20 20 54 68 65 72  8 strings.  Ther
d3c0: 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
d3d0: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
d3e0: 72 61 79 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69  ray.  .** The fi
d3f0: 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
d400: 6f 69 6e 74 20 74 6f 20 7a 65 72 6f 2d 74 65 72  oint to zero-ter
d410: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
d420: 74 68 61 74 20 0a 2a 2a 20 63 6f 6e 74 61 69 6e  that .** contain
d430: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
d440: 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
d450: 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
d460: 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
d470: 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
d480: 20 4e 55 4c 4c 0a 2a 2a 20 76 61 6c 75 65 73 20   NULL.** values 
d490: 61 72 65 20 67 69 76 65 20 61 20 4e 55 4c 4c 20  are give a NULL 
d4a0: 70 6f 69 6e 74 65 72 2e 20 20 41 6c 6c 20 6f 74  pointer.  All ot
d4b0: 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
d4c0: 6e 0a 2a 2a 20 74 68 65 69 72 20 55 54 46 2d 38  n.** their UTF-8
d4d0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
d4e0: 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
d4f0: 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
d500: 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
d510: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
d520: 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
d530: 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
d540: 73 69 73 74 73 20 6f 66 20 6f 6e 65 20 6f 72 20  sists of one or 
d550: 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
d560: 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
d570: 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
d580: 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
d590: 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
d5a0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
d5b0: 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
d5c0: 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
d5d0: 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
d5e0: 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
d5f0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61  e()]..**.** As a
d600: 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
d610: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
d620: 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
d630: 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
d640: 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
d650: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
d660: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
d670: 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
d680: 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
d690: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
d6a0: 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
d6b0: 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
d6c0: 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
d6d0: 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
d6e0: 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
d6f0: 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
d700: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
d710: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
d720: 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
d730: 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
d740: 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
d750: 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
d760: 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
d770: 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
d780: 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
d790: 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
d7a0: 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
d7b0: 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
d7c0: 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
d7d0: 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
d7e0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
d7f0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
d800: 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
d810: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
d820: 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
d830: 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
d840: 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
d850: 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
d860: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
d870: 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
d880: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
d890: 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
d8a0: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
d8b0: 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
d8c0: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
d8d0: 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
d8e0: 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
d8f0: 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
d900: 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
d910: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
d920: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d930: 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
d940: 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
d950: 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
d960: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
d970: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
d980: 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
d990: 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
d9a0: 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
d9b0: 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  nd parameter.  I
d9c0: 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  t returns a resu
d9d0: 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
d9e0: 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
d9f0: 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
da00: 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
da10: 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  er the calling f
da20: 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  unction has fini
da30: 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72  shed using the r
da40: 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64  esult, it should
da50: 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f   .** pass the po
da60: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65 73  inter to the res
da70: 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c  ult table to sql
da80: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
da90: 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 0a 2a  ) in order to .*
daa0: 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
dab0: 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
dac0: 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
dad0: 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 20   of the way the 
dae0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
daf0: 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
db00: 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
db10: 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
db20: 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
db30: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
db40: 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
db50: 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
db60: 79 2e 20 20 4f 6e 6c 79 20 0a 2a 2a 20 5b 73 71  y.  Only .** [sq
db70: 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
db80: 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
db90: 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
dba0: 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
dbb0: 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
dbc0: 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
dbd0: 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
dbe0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
dbf0: 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
dc00: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
dc10: 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
dc20: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
dc30: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
dc40: 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
dc50: 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
dc60: 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
dc70: 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
dc80: 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
dc90: 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
dca0: 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
dcb0: 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
dcc0: 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
dcd0: 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
dce0: 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
dcf0: 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
dd00: 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
dd10: 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
dd20: 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
dd30: 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
dd40: 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
dd50: 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
dd60: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
dd70: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
dd80: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
dd90: 33 37 31 7d 20 49 66 20 61 20 5b 73 71 6c 69 74  371} If a [sqlit
dda0: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
ddb0: 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61  fails a memory a
ddc0: 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a  llocation, then.
ddd0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20 66  **          it f
dde0: 72 65 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  rees the result 
ddf0: 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73  table under cons
de00: 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 73  truction, aborts
de10: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
de20: 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73   query in proces
de30: 73 2c 20 73 6b 69 70 73 20 61 6e 79 20 73 75 62  s, skips any sub
de40: 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c  sequent queries,
de50: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 20 20 20   sets the.**    
de60: 20 20 20 20 20 20 2a 72 65 73 75 6c 74 70 20 6f        *resultp o
de70: 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f  utput pointer to
de80: 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e   NULL and return
de90: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  s [SQLITE_NOMEM]
dea0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d  ..**.** {F12373}
deb0: 20 49 66 20 74 68 65 20 6e 63 6f 6c 75 6d 6e 20   If the ncolumn 
dec0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
ded0: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
dee0: 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a  )] is not NULL.*
def0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
df00: 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
df10: 6c 65 28 29 5d 20 77 72 69 74 65 20 74 68 65 20  le()] write the 
df20: 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
df30: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  s in the.**     
df40: 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20       result set 
df50: 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74  of the query int
df60: 6f 20 2a 6e 63 6f 6c 75 6d 6e 20 69 66 20 74 68  o *ncolumn if th
df70: 65 20 71 75 65 72 79 20 69 73 0a 2a 2a 20 20 20  e query is.**   
df80: 20 20 20 20 20 20 20 73 75 63 63 65 73 73 66 75         successfu
df90: 6c 20 28 69 66 20 74 68 65 20 66 75 6e 63 74 69  l (if the functi
dfa0: 6f 6e 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  on returns SQLIT
dfb0: 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  E_OK)..**.** {F1
dfc0: 32 33 37 34 7d 20 49 66 20 74 68 65 20 6e 72 6f  2374} If the nro
dfd0: 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  w parameter to [
dfe0: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
dff0: 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  e()] is not NULL
e000: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
e010: 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  n [sqlite3_get_t
e020: 61 62 6c 65 28 29 5d 20 77 72 69 74 65 20 74 68  able()] write th
e030: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
e040: 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
e050: 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f      result set o
e060: 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f  f the query into
e070: 20 2a 6e 72 6f 77 20 69 66 20 74 68 65 20 71 75   *nrow if the qu
e080: 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ery is.**       
e090: 20 20 20 73 75 63 63 65 73 73 66 75 6c 20 28 69     successful (i
e0a0: 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72  f the function r
e0b0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
e0c0: 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 36  )..**.** {F12376
e0d0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
e0e0: 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 75 6e 63  et_table()] func
e0f0: 74 69 6f 6e 20 73 65 74 73 20 69 74 73 20 2a 6e  tion sets its *n
e100: 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 0a 2a 2a 20  column value.** 
e110: 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
e120: 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
e130: 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
e140: 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79  set of the query
e150: 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
e160: 20 20 20 20 73 71 6c 20 70 61 72 61 6d 65 74 65      sql paramete
e170: 72 2c 20 6f 72 20 74 6f 20 7a 65 72 6f 20 69 66  r, or to zero if
e180: 20 74 68 65 20 71 75 65 72 79 20 69 6e 20 73 71   the query in sq
e190: 6c 20 68 61 73 20 61 6e 20 65 6d 70 74 79 0a 2a  l has an empty.*
e1a0: 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
e1b0: 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  t set..*/.int sq
e1c0: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
e1d0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
e1e0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
e1f0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
e200: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
e210: 6c 2c 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  l,      /* SQL t
e220: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
e230: 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 52 65 73  /.  char ***pRes
e240: 75 6c 74 2c 20 20 20 20 20 20 2f 2a 20 52 65 73  ult,      /* Res
e250: 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
e260: 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77  y */.  int *nrow
e270: 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
e280: 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
e290: 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
e2a0: 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f  re */.  int *nco
e2b0: 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20 2f 2a  lumn,         /*
e2c0: 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
e2d0: 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
e2e0: 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
e2f0: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
e300: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
e310: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
e320: 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
e330: 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
e340: 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
e350: 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
e360: 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
e370: 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b  ting Functions {
e380: 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F17400}.**.** Th
e390: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
e3a0: 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74   workalikes of t
e3b0: 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
e3c0: 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
e3d0: 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
e3e0: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
e3f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
e400: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
e410: 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
e420: 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
e430: 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
e440: 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
e450: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
e460: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
e470: 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
e480: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
e490: 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
e4a0: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
e4b0: 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
e4c0: 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 20 42 6f  e3_free()].   Bo
e4d0: 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
e4e0: 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
e4f0: 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
e500: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
e510: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
e520: 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
e530: 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
e540: 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
e550: 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33  **.** In sqlite3
e560: 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
e570: 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
e580: 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
e590: 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
e5a0: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
e5b0: 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
e5c0: 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
e5d0: 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
e5e0: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
e5f0: 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
e600: 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
e610: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
e620: 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
e630: 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
e640: 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
e650: 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
e660: 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
e670: 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69  rintf().  This i
e680: 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
e690: 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
e6a0: 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
e6b0: 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
e6c0: 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
e6d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e  ompatibility.  N
e6e0: 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
e6f0: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
e700: 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
e710: 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
e720: 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
e730: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
e740: 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
e750: 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
e760: 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57 65   the buffer.  We
e770: 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
e780: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
e790: 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
e7a0: 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
e7b0: 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
e7c0: 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
e7d0: 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
e7e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
e7f0: 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
e800: 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
e810: 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
e820: 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
e830: 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  * As long as the
e840: 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
e850: 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
e860: 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
e870: 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
e880: 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
e890: 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
e8a0: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
e8b0: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
e8c0: 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
e8d0: 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
e8e0: 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
e8f0: 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
e900: 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
e910: 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
e920: 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
e930: 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
e940: 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
e950: 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
e960: 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  racters..**.** T
e970: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
e980: 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
e990: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
e9a0: 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
e9b0: 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
e9c0: 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
e9d0: 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
e9e0: 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
e9f0: 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
ea00: 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
ea10: 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
ea20: 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
ea30: 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
ea40: 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
ea50: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
ea60: 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
ea70: 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
ea80: 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
ea90: 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
eaa0: 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
eab0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
eac0: 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
ead0: 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
eae0: 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
eaf0: 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
eb00: 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
eb10: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
eb20: 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
eb30: 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
eb40: 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
eb50: 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
eb60: 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
eb70: 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
eb80: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
eb90: 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
eba0: 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74 72 69 6e  e, so some strin
ebb0: 67 20 76 61 72 69 61 62 6c 65 20 63 6f 6e 74 61  g variable conta
ebc0: 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
ebd0: 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
ebe0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
ebf0: 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
ec00: 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
ec10: 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
ec20: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
ec30: 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
ec40: 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
ec50: 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
ec60: 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
ec70: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
ec80: 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
ec90: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
eca0: 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
ecb0: 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
ecc0: 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
ecd0: 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
ece0: 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
ecf0: 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
ed00: 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
ed10: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
ed20: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
ed30: 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
ed40: 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
ed50: 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
ed60: 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
ed70: 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
ed80: 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
ed90: 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
eda0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
edb0: 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
edc0: 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
edd0: 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
ede0: 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
edf0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
ee00: 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
ee10: 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
ee20: 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
ee30: 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
ee40: 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
ee50: 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
ee60: 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
ee70: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
ee80: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
ee90: 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
eea0: 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
eeb0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
eec0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
eed0: 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
eee0: 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
eef0: 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
ef00: 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 0a  eneral rule you.
ef10: 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  ** should always
ef20: 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
ef30: 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
ef40: 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
ef50: 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c 69 74 65   string .** lite
ef60: 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25  ral..**.** The %
ef70: 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
ef80: 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
ef90: 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
efa0: 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
efb0: 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
efc0: 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
efd0: 6e 67 2e 20 20 4f 72 20 69 66 20 74 68 65 20 70  ng.  Or if the p
efe0: 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
eff0: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74  argument.** list
f000: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
f010: 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
f020: 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
f030: 4c 22 20 28 77 69 74 68 6f 75 74 20 73 69 6e 67  L" (without sing
f040: 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29 20 69 6e  le.** quotes) in
f050: 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51   place of the %Q
f060: 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20 20   option. {END}  
f070: 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
f080: 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
f090: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
f0a0: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
f0b0: 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
f0c0: 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
f0d0: 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
f0e0: 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
f0f0: 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
f100: 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
f110: 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
f120: 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
f130: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
f140: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
f150: 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
f160: 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
f170: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
f180: 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
f190: 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
f1a0: 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
f1b0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
f1c0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25  er..**.** The "%
f1d0: 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
f1e0: 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74  tion works exact
f1f0: 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74  ly like "%s" wit
f200: 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
f210: 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
f220: 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
f230: 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
f240: 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
f250: 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
f260: 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
f270: 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
f280: 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ing. {END}.**.**
f290: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
f2a0: 2a 2a 20 7b 46 31 37 34 30 33 7d 20 20 54 68 65  ** {F17403}  The
f2b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
f2c0: 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  f()] and [sqlite
f2d0: 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_vmprintf()] in
f2e0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20  terfaces.**     
f2f0: 20 20 20 20 20 20 72 65 74 75 72 6e 20 65 69 74        return eit
f300: 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  her pointers to 
f310: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
f320: 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65  UTF-8 strings he
f330: 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ld in.**        
f340: 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e     memory obtain
f350: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
f360: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55  _malloc()] or NU
f370: 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a  LL pointers if.*
f380: 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 63 61  *           a ca
f390: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ll to [sqlite3_m
f3a0: 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a  alloc()] fails..
f3b0: 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 36 7d 20 20  **.** {F17406}  
f3c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  The [sqlite3_snp
f3d0: 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61  rintf()] interfa
f3e0: 63 65 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f  ce writes a zero
f3f0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
f400: 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73           UTF-8 s
f410: 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62  tring into the b
f420: 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f  uffer pointed to
f430: 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
f440: 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
f450: 20 20 20 20 20 20 70 72 6f 76 69 64 65 64 20 74        provided t
f460: 68 61 74 20 74 68 65 20 66 69 72 73 74 20 70 61  hat the first pa
f470: 72 61 6d 65 74 65 72 20 69 73 20 67 72 65 61 74  rameter is great
f480: 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a  er than zero..**
f490: 0a 2a 2a 20 7b 46 31 37 34 30 37 7d 20 20 54 68  .** {F17407}  Th
f4a0: 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  e [sqlite3_snpri
f4b0: 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ntf()] interface
f4c0: 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 73   does not writes
f4d0: 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20   slots of.**    
f4e0: 20 20 20 20 20 20 20 69 74 73 20 6f 75 74 70 75         its outpu
f4f0: 74 20 62 75 66 66 65 72 20 28 74 68 65 20 73 65  t buffer (the se
f500: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29 20  cond parameter) 
f510: 6f 75 74 73 69 64 65 20 74 68 65 20 72 61 6e 67  outside the rang
f520: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  e.**           o
f530: 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31 20  f 0 through N-1 
f540: 28 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20  (where N is the 
f550: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 29  first parameter)
f560: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
f570: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
f580: 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
f590: 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
f5a0: 20 20 72 65 71 75 65 73 74 65 64 20 62 79 20 74    requested by t
f5b0: 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69 66  he format specif
f5c0: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 20 20 0a 2a  ication..**   .*
f5d0: 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
f5e0: 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
f5f0: 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
f600: 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
f610: 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
f620: 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
f630: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
f640: 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
f650: 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
f660: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
f670: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
f680: 75 62 73 79 73 74 65 6d 20 7b 46 31 37 33 30 30  ubsystem {F17300
f690: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  }.**.** The SQLi
f6a0: 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68  te core  uses th
f6b0: 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
f6c0: 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
f6d0: 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
f6e0: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
f6f0: 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
f700: 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
f710: 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
f720: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
f730: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
f740: 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
f750: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
f760: 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
f770: 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
f780: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
f790: 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
f7a0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
f7b0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f7c0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
f7d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
f7e0: 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
f7f0: 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
f800: 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
f810: 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
f820: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73  rameter..** If s
f830: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
f840: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
f850: 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
f860: 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
f870: 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
f880: 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68   pointer.  If th
f890: 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
f8a0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
f8b0: 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
f8c0: 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
f8d0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
f8e0: 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
f8f0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
f900: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
f910: 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
f920: 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
f930: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
f940: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f950: 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
f960: 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
f970: 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
f980: 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
f990: 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73  e reused.  The s
f9a0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
f9b0: 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
f9c0: 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
f9d0: 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
f9e0: 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
f9f0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
fa00: 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
fa10: 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
fa20: 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
fa30: 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
fa40: 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
fa50: 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
fa60: 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
fa70: 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
fa80: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
fa90: 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
faa0: 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
fab0: 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
fac0: 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
fad0: 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
fae0: 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
faf0: 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
fb00: 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
fb10: 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
fb20: 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
fb30: 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
fb40: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
fb50: 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
fb60: 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
fb70: 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
fb80: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a  qlite3_free()..*
fb90: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
fba0: 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
fbb0: 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
fbc0: 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
fbd0: 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
fbe0: 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
fbf0: 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
fc00: 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
fc10: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
fc20: 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
fc30: 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
fc40: 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
fc50: 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
fc60: 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70    If the first p
fc70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
fc80: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
fc90: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
fca0: 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
fcb0: 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
fcc0: 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
fcd0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
fce0: 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
fcf0: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
fd00: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
fd10: 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68  lloc()..** If th
fd20: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
fd30: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
fd40: 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
fd50: 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
fd60: 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
fd70: 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
fd80: 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
fd90: 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
fda0: 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
fdb0: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
fdc0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
fdd0: 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 53 71 6c 69 74  lloc()..** Sqlit
fde0: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
fdf0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
fe00: 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
fe10: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
fe20: 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
fe30: 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
fe40: 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
fe50: 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
fe60: 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65  ..** If M is the
fe70: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
fe80: 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
fe90: 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
fea0: 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
feb0: 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
fec0: 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
fed0: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
fee0: 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
fef0: 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
ff00: 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70  lloc() and the p
ff10: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
ff20: 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20  is freed..** If 
ff30: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
ff40: 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
ff50: 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
ff60: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
ff70: 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
ff80: 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75   The memory retu
ff90: 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
ffa0: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c  malloc() and sql
ffb0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
ffc0: 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
ffd0: 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
ffe0: 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
fff0: 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ry. {END}.**.** 
10000 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c  The default impl
10010 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66  ementation.** of
10020 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
10030 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
10040 20 75 73 65 73 20 74 68 65 20 6d 61 6c 6c 6f 63   uses the malloc
10050 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  (), realloc().**
10060 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76   and free() prov
10070 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e  ided by the stan
10080 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
10090 7b 46 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72  {F17382} However
100a0 2c 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65 20  , if .** SQLite 
100b0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
100c0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43   the following C
100d0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
100e0 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  cro.**.** <block
100f0 71 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4d 45  quote> SQLITE_ME
10100 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e  MORY_SIZE=<i>NNN
10110 3c 2f 69 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  </i> </blockquot
10120 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 3c  e>.**.** where <
10130 69 3e 4e 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e 20  i>NNN</i> is an 
10140 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 20 53 51  integer, then SQ
10150 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74  Lite create a st
10160 61 74 69 63 0a 2a 2a 20 61 72 72 61 79 20 6f 66  atic.** array of
10170 20 61 74 20 6c 65 61 73 74 20 3c 69 3e 4e 4e 4e   at least <i>NNN
10180 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69  </i> bytes in si
10190 7a 65 20 61 6e 64 20 75 73 65 20 74 68 61 74 20  ze and use that 
101a0 61 72 72 61 79 0a 2a 2a 20 66 6f 72 20 61 6c 6c  array.** for all
101b0 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
101c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
101d0 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20  n needs. {END}  
101e0 41 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 6d 65  Additional.** me
101f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
10200 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
10210 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
10220 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e  leases..**.** In
10230 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
10240 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
10250 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
10260 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
10270 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
10280 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
10290 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
102a0 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
102b0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
102c0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
102d0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
102e0 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
102f0 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
10300 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
10310 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
10320 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
10330 6e 20 62 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a 2a  n be.** used..**
10340 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
10350 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
10360 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
10370 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
10380 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
10390 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
103a0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
103b0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
103c0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
103d0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
103e0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
103f0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
10400 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
10410 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
10420 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
10430 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
10440 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
10450 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
10460 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
10470 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
10480 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
10490 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
104a0 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
104b0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
104c0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
104d0 0a 2a 2a 20 7b 46 31 37 33 30 33 7d 20 20 54 68  .** {F17303}  Th
104e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
104f0 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  c(N)] interface 
10500 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61  returns either a
10510 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a 2a 20   pointer to .** 
10520 20 20 20 20 20 20 20 20 20 20 6e 65 77 6c 79 20            newly 
10530 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63  checked-out bloc
10540 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  k of at least N 
10550 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a  bytes of memory.
10560 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
10570 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67  t is 8-byte alig
10580 6e 65 64 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20  ned, .**        
10590 20 20 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73     or it returns
105a0 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75   NULL if it is u
105b0 6e 61 62 6c 65 20 74 6f 20 66 75 6c 66 69 6c 6c  nable to fulfill
105c0 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a   the request..**
105d0 0a 2a 2a 20 7b 46 31 37 33 30 34 7d 20 20 54 68  .** {F17304}  Th
105e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
105f0 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  c(N)] interface 
10600 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
10610 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20  ointer if.**    
10620 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73         N is less
10630 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
10640 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46  o zero..**.** {F
10650 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c  17305}  The [sql
10660 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e  ite3_free(P)] in
10670 74 65 72 66 61 63 65 20 72 65 6c 65 61 73 65 73  terface releases
10680 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73   memory previous
10690 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ly.**           
106a0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
106b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
106c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
106d0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  lloc()],.**     
106e0 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20        making it 
106f0 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65  available for re
10700 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  use..**.** {F173
10710 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b  06}  A call to [
10720 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c  sqlite3_free(NUL
10730 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73  L)] is a harmles
10740 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b  s no-op..**.** {
10750 46 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20  F17310}  A call 
10760 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  to [sqlite3_real
10770 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75  loc(0,N)] is equ
10780 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c  ivalent to a cal
10790 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  l.**           t
107a0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
107b0 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  c(N)]..**.** {F1
107c0 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7312}  A call to
107d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
107e0 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76  c(P,0)] is equiv
107f0 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a  alent to a call.
10800 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
10810 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29  [sqlite3_free(P)
10820 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35  ]..**.** {F17315
10830 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  }  The SQLite co
10840 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33  re uses [sqlite3
10850 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
10860 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c  ite3_realloc()],
10870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e  .**           an
10880 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  d [sqlite3_free(
10890 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  )] for all of it
108a0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
108b0 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
108c0 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f       deallocatio
108d0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b  n needs..**.** {
108e0 46 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71  F17318}  The [sq
108f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
10900 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
10910 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70  turns either a p
10920 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
10930 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f      to a block o
10940 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65  f checked-out me
10950 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74  mory of at least
10960 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
10970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
10980 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69  at is 8-byte ali
10990 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20  gned, or a NULL 
109a0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
109b0 46 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73  F17321}  When [s
109c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
109d0 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e  ,N)] returns a n
109e0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
109f0 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20   it first.**    
10a00 20 20 20 20 20 20 20 63 6f 70 69 65 73 20 74 68         copies th
10a10 65 20 66 69 72 73 74 20 4b 20 62 79 74 65 73 20  e first K bytes 
10a20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20  of content from 
10a30 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79  P into the newly
10a40 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20   allocated.**   
10a50 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4b 20          where K 
10a60 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66  is the lesser of
10a70 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20   N and the size 
10a80 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 50 2e  of the buffer P.
10a90 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 32 7d 20  .**.** {F17322} 
10aa0 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   When [sqlite3_r
10ab0 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74  ealloc(P,N)] ret
10ac0 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  urns a non-NULL 
10ad0 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73  pointer, it firs
10ae0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  t.**           r
10af0 65 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 66  eleases the buff
10b00 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  er P..**.** {F17
10b10 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69  323}  When [sqli
10b20 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
10b30 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ] returns NULL, 
10b40 74 68 65 20 62 75 66 66 65 72 20 50 20 69 73 0a  the buffer P is.
10b50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74  **           not
10b60 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c   modified or rel
10b70 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  eased..**.** LIM
10b80 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
10b90 7b 55 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f  {U17350}  The po
10ba0 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
10bb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
10bc0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
10bd0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20  _realloc()].**  
10be0 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 65           must be
10bf0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
10c00 65 6c 73 65 20 61 20 70 6f 69 6e 74 65 72 20 6f  else a pointer o
10c10 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
10c20 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rior.**         
10c30 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20    invocation of 
10c40 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
10c50 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
10c60 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
10c70 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  as.**           
10c80 6e 6f 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  not been release
10c90 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 31  d..**.** {U17351
10ca0 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  }  The applicati
10cb0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
10cc0 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
10cd0 72 74 20 6f 66 20 0a 2a 2a 20 20 20 20 20 20 20  rt of .**       
10ce0 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d      a block of m
10cf0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
10d00 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
10d10 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
10d20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65      [sqlite3_fre
10d30 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
10d40 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a  _realloc()]..**.
10d50 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
10d60 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
10d70 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
10d80 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
10d90 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
10da0 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
10db0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
10dc0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
10dd0 74 69 73 74 69 63 73 20 7b 46 31 37 33 37 30 7d  tistics {F17370}
10de0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
10df0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
10e00 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
10e10 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
10e20 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
10e30 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
10e40 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
10e50 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
10e60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
10e70 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
10e80 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
10e90 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  em included with
10ea0 69 6e 20 74 68 65 20 53 51 4c 69 74 65 2e 0a 2a  in the SQLite..*
10eb0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
10ec0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 31 7d 20  .**.** {F17371} 
10ed0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
10ee0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
10ef0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
10f00 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
10f10 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 6d  er of bytes of m
10f20 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
10f30 6f 75 74 73 74 61 6e 64 69 6e 67 20 0a 2a 2a 20  outstanding .** 
10f40 20 20 20 20 20 20 20 20 20 28 6d 61 6c 6c 6f 63           (malloc
10f50 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
10f60 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 33  )..**.** {F17373
10f70 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  } The [sqlite3_m
10f80 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
10f90 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
10fa0 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
10fb0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
10fc0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
10fd0 6f 72 79 5f 75 73 65 64 28 29 5d 20 0a 2a 2a 20  ory_used()] .** 
10fe0 20 20 20 20 20 20 20 20 20 73 69 6e 63 65 20 74           since t
10ff0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
11000 72 6b 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  rk was last rese
11010 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 34  t..**.** {F17374
11020 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74  } The values ret
11030 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
11040 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
11050 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
11060 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
11070 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
11080 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
11090 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ad.**          a
110a0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
110b0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
110c0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
110d0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  _malloc()],.**  
110e0 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20          but not 
110f0 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
11100 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
11110 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
11120 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ary.**          
11130 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
11140 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11150 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 20 0a 2a   may call..** .*
11160 2a 20 7b 46 31 37 33 37 35 7d 20 54 68 65 20 6d  * {F17375} The m
11170 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
11180 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
11190 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
111a0 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  lue of.**       
111b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
111c0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
111d0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
111e0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
111f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
11200 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
11210 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68  ()] is true.  Th
11220 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
11230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
11240 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
11250 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
11260 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
11270 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  mark.**         
11280 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
11290 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
112a0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
112b0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
112c0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
112d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
112e0 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
112f0 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
11300 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
11310 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
11320 6e 65 72 61 74 6f 72 20 7b 46 31 37 33 39 30 7d  nerator {F17390}
11330 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
11340 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
11350 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
11360 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
11370 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
11380 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
11390 6e 64 6f 6d 20 52 4f 57 49 44 73 20 77 68 65 6e  ndom ROWIDs when
113a0 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
113b0 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
113c0 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
113d0 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
113e0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 52 4f  gest possible RO
113f0 57 49 44 2e 20 20 54 68 65 20 50 52 4e 47 20 69  WID.  The PRNG i
11400 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
11410 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
11420 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
11430 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
11440 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
11450 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
11460 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
11470 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
11480 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
11490 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
114a0 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  * A call to this
114b0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
114c0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
114d0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
114e0 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  r P..**.** The f
114f0 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72  irst time this r
11500 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65  outine is invoke
11510 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e  d (either intern
11520 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68  ally or by.** th
11530 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74  e application) t
11540 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
11550 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
11560 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ss obtained.** f
11570 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
11580 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
11590 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
115a0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
115b0 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71  ** On all subseq
115c0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
115d0 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  , the pseudo-ran
115e0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
115f0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
11600 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
11610 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
11620 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
11630 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
11640 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  od..**.** INVARI
11650 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ANTS:.**.** {F17
11660 33 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  392} The [sqlite
11670 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50  3_randomness(N,P
11680 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69  )] interface wri
11690 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a  tes N bytes of.*
116a0 2a 20 20 20 20 20 20 20 20 20 20 68 69 67 68 2d  *          high-
116b0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
116c0 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
116d0 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64  uffer P..*/.void
116e0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
116f0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
11700 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
11710 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
11720 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
11730 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 35   Callbacks {F125
11740 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00}.**.** This r
11750 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
11760 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   a authorizer ca
11770 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
11780 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
11790 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
117a0 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
117b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
117c0 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  t..** The author
117d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
117e0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
117f0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
11800 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
11810 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
11820 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
11830 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
11840 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
11850 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
11860 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
11870 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
11880 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f  v2()].  At vario
11890 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
118a0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
118b0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
118c0 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
118d0 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
118e0 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
118f0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
11900 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
11910 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
11920 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
11930 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
11940 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72    The authorizer
11950 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
11960 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
11970 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
11980 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
11990 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
119a0 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
119b0 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
119c0 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
119d0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
119e0 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
119f0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
11a00 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
11a10 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
11a20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
11a30 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
11a40 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 20  ith an error.   
11a50 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
11a60 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
11a70 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
11a80 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
11a90 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
11aa0 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
11ab0 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
11ac0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
11ad0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
11ae0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
11af0 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
11b00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
11b10 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
11b20 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
11b30 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
11b40 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
11b50 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
11b60 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
11b70 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
11b80 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68   is ok.  When th
11b90 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
11ba0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
11bb0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
11bc0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
11bd0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
11be0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
11bf0 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
11c00 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
11c10 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
11c20 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
11c30 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
11c40 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65   denied.  If the
11c50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
11c60 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
11c70 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
11c80 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
11c90 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
11ca0 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
11cb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
11cc0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
11cd0 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
11ce0 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
11cf0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
11d00 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
11d10 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
11d20 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
11d30 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
11d40 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
11d50 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
11d60 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
11d70 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
11d80 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
11d90 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
11da0 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
11db0 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
11dc0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
11dd0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
11de0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
11df0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
11e00 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69 72  y of.** the thir
11e10 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
11e20 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
11e30 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
11e40 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65  rface..** The se
11e50 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
11e60 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
11e70 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a  s an integer .**
11e80 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
11e90 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
11ea0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
11eb0 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
11ec0 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75 74 68 6f  n.** to be autho
11ed0 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64  rized. The third
11ee0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 0a 2a   through sixth.*
11ef0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  * parameters to 
11f00 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
11f10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
11f20 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
11f30 6e 74 61 69 6e 20 0a 2a 2a 20 61 64 64 69 74 69  ntain .** additi
11f40 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f  onal details abo
11f50 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
11f60 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
11f70 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
11f80 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
11f90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
11fa0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
11fb0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
11fc0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
11fd0 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74 6f  ed.** source, to
11fe0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
11ff0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
12000 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
12010 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74 68 61  cess data.** tha
12020 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  t they are not a
12030 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
12040 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
12050 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78 65  ot try to.** exe
12060 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
12070 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
12080 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
12090 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
120a0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
120b0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
120c0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
120d0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
120e0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
120f0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
12100 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
12110 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
12120 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
12130 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
12140 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
12150 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
12160 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
12170 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
12180 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
12190 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
121a0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
121b0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
121c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
121d0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
121e0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
121f0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
12200 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
12210 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
12220 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
12230 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
12240 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
12250 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
12260 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
12270 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
12280 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
12290 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
122a0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
122b0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
122c0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
122d0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
122e0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
122f0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
12300 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  orizer..**.** On
12310 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
12320 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
12330 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
12340 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
12350 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
12360 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
12370 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
12380 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
12390 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
123a0 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20  l.  Disable the 
123b0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
123c0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
123d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
123e0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
123f0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
12400 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  lt..**.** Note t
12410 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
12420 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
12430 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
12440 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
12450 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
12460 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
12470 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
12480 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
12490 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
124a0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
124b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
124c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
124d0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 31 7d  :.**.** {F12501}
124e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
124f0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e  t_authorizer(D,.
12500 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ..)] interface r
12510 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20  egisters a.**   
12520 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65         authorize
12530 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
12540 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12550 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ion D..**.** {F1
12560 32 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72  2502} The author
12570 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
12580 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
12590 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
125a0 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67  *          being
125b0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 0a 2a 2a 20   compiled.**.** 
125c0 7b 46 31 32 35 30 33 7d 20 49 66 20 74 68 65 20  {F12503} If the 
125d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
125e0 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ack returns any 
125f0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
12600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
12610 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
12620 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
12630 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 68 65 6e  QLITE_DENY] then
12640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
12650 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
12660 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
12670 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
12680 63 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20  caused.**       
12690 20 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65     the authorize
126a0 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75  r callback to ru
126b0 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74  n shall fail wit
126c0 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  h an.**         
126d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
126e0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61  error code and a
126f0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
12700 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
12710 2a 2a 20 7b 46 31 32 35 30 34 7d 20 57 68 65 6e  ** {F12504} When
12720 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
12730 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
12740 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
12750 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20  e operation.**  
12760 20 20 20 20 20 20 20 20 64 65 73 63 72 69 62 65          describe
12770 64 20 69 73 20 63 6f 64 65 64 20 6e 6f 72 6d 61  d is coded norma
12780 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  lly..**.** {F125
12790 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74  05} When the aut
127a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
127b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
127c0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20  _DENY], the.**  
127d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
127e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
127f0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
12800 6c 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  l that caused th
12810 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75  e.**          au
12820 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
12830 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66  k to run shall f
12840 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ail.**          
12850 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f  with an [SQLITE_
12860 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64  ERROR] error cod
12870 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  e and an error m
12880 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20  essage.**       
12890 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68     explaining th
128a0 61 74 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  at access is den
128b0 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  ied..**.** {F125
128c0 30 36 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  06} If the autho
128d0 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20  rizer code (the 
128e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
128f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a   the authorizer.
12900 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
12910 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45  back) is [SQLITE
12920 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61  _READ] and the a
12930 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
12940 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ck returns.**   
12950 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
12960 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
12970 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12980 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
12990 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
129a0 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76   insert a NULL v
129b0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
129c0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
129d0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
129e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  e.**          be
129f0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
12a00 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
12a10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
12a20 7b 46 31 32 35 30 37 7d 20 49 66 20 74 68 65 20  {F12507} If the 
12a30 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
12a40 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74  (the 2nd paramet
12a50 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
12a60 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  izer.**         
12a70 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e   callback) is an
12a80 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ything other tha
12a90 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c  n [SQLITE_READ],
12aa0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
12ab0 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53    a return of [S
12ac0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61  QLITE_IGNORE] ha
12ad0 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63  s the same effec
12ae0 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  t as [SQLITE_DEN
12af0 59 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  Y]. .**.** {F125
12b00 31 30 7d 20 54 68 65 20 66 69 72 73 74 20 70 61  10} The first pa
12b10 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
12b20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
12b30 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
12b40 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
12b50 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
12b60 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
12b70 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
12b80 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
12b90 2a 2a 20 7b 46 31 32 35 31 31 7d 20 54 68 65 20  ** {F12511} The 
12ba0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12bb0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
12bc0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a   is an integer .
12bd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
12be0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
12bf0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
12c00 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69  cifies the parti
12c10 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20  cular action.** 
12c20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65 20 61           to be a
12c30 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
12c40 20 7b 46 31 32 35 31 32 7d 20 54 68 65 20 74 68   {F12512} The th
12c50 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
12c60 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
12c70 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
12c80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
12c90 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
12ca0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
12cb0 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  n .**          a
12cc0 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c  dditional detail
12cd0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
12ce0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
12cf0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  zed..**.** {F125
12d00 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  20} Each call to
12d10 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
12d20 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72  thorizer()] over
12d30 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  rides the.**    
12d40 20 20 20 20 20 20 61 6e 79 20 70 72 65 76 69 6f        any previo
12d50 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 61  usly installed a
12d60 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
12d70 20 7b 46 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c   {F12521} A NULL
12d80 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e   authorizer mean
12d90 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72  s that no author
12da0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ization.**      
12db0 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20      callback is 
12dc0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
12dd0 46 31 32 35 32 32 7d 20 54 68 65 20 64 65 66 61  F12522} The defa
12de0 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69  ult authorizer i
12df0 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  s NULL..*/.int s
12e00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
12e10 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
12e20 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
12e30 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
12e40 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
12e50 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
12e60 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
12e70 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
12e80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12e90 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
12ea0 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 46 31 32  eturn Codes {F12
12eb0 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  590}.**.** The [
12ec0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
12ed0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
12ee0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
12ef0 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
12f00 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
12f10 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
12f20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
12f30 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
12f40 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
12f50 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
12f60 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
12f70 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
12f80 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
12f90 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
12fa0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
12fb0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
12fc0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
12fd0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64  formation..*/.#d
12fe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
12ff0 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
13000 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
13010 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
13020 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13030 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
13040 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
13050 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
13060 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
13070 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
13080 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
13090 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 46 31  Action Codes {F1
130a0 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2550}.**.** The 
130b0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
130c0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
130d0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
130e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
130f0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
13100 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
13110 7a 65 72 20 63 65 72 74 61 69 6e 20 53 51 4c 20  zer certain SQL 
13120 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
13130 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
13140 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
13150 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
13160 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
13170 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
13180 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
13190 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
131a0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
131b0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
131c0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
131d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
131e0 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
131f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
13200 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
13210 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
13220 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
13230 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a 20  on is to be .** 
13240 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
13250 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
13260 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
13270 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
13280 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
13290 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
132a0 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
132b0 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
132c0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
132d0 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
132e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
132f0 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61  r.  The 5th para
13300 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
13310 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
13320 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
13330 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
13340 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
13350 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70   .** etc.) if ap
13360 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36  plicable.  The 6
13370 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
13380 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
13390 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
133a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
133b0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
133c0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
133d0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
133e0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
133f0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
13400 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
13410 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
13420 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c  y from .** top-l
13430 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
13440 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
13450 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 31 7d 20  .**.** {F12551} 
13460 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
13470 65 74 65 72 20 74 6f 20 61 6e 20 0a 2a 2a 20 20  eter to an .**  
13480 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
13490 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
134a0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
134b0 6c 62 61 63 6b 5d 20 69 73 20 61 6c 77 61 79 73  lback] is always
134c0 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20   an integer.**  
134d0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
134e0 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65  COPY | authorize
134f0 72 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  r code] that spe
13500 63 69 66 69 65 73 20 77 68 61 74 20 61 63 74 69  cifies what acti
13510 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  on.**          i
13520 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
13530 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35  ed..**.** {F1255
13540 32 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  2} The 3rd and 4
13550 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
13560 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
13570 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
13580 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
13590 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61  orization callba
135a0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20  ck function].** 
135b0 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 62 65           will be
135c0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
135d0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
135e0 20 77 68 69 63 68 20 0a 2a 2a 20 20 20 20 20 20   which .**      
135f0 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59      [SQLITE_COPY
13600 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f   | authorizer co
13610 64 65 5d 20 69 73 20 75 73 65 64 20 61 73 20 74  de] is used as t
13620 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13630 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  ter..**.** {F125
13640 35 33 7d 20 54 68 65 20 35 74 68 20 70 61 72 61  53} The 5th para
13650 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
13660 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
13670 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
13680 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
13690 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e  llback] is the n
136a0 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
136b0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
136c0 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22  (example: "main"
136d0 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29 20  , "temp", etc.) 
136e0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a  if applicable..*
136f0 2a 0a 2a 2a 20 7b 46 31 32 35 35 34 7d 20 54 68  *.** {F12554} Th
13700 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
13710 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
13720 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
13730 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
13740 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
13750 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  ] is the name.**
13760 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
13770 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
13780 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
13790 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
137a0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
137b0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
137c0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
137d0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
137e0 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
137f0 6f 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  om .**          
13800 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
13810 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
13820 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13830 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13840 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
13850 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
13860 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
13870 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
13880 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
13890 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
138a0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
138b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
138c0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
138d0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
138e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
138f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13900 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13910 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
13920 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
13930 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
13940 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13950 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13960 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
13970 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
13980 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
13990 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
139a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
139b0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
139c0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
139d0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
139e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
139f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13a00 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
13a10 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
13a20 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
13a30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
13a40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13a50 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
13a60 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
13a70 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
13a80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
13a90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
13aa0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
13ab0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
13ac0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
13ad0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13ae0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
13af0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
13b00 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
13b10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
13b20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
13b30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
13b40 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
13b50 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
13b60 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
13b70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
13b80 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
13b90 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
13ba0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
13bb0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
13bc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13bd0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
13be0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
13bf0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
13c00 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
13c10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
13c20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
13c30 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
13c40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
13c50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
13c60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13c70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
13c80 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
13c90 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
13ca0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
13cb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13cc0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
13cd0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
13ce0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
13cf0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
13d00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13d10 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
13d20 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
13d30 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
13d40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
13d50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13d60 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
13d70 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
13d80 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
13d90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13da0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13db0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
13dc0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
13dd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13de0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13df0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13e00 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
13e10 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
13e20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
13e30 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
13e40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13e50 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
13e60 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
13e70 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
13e80 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
13e90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13ea0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
13eb0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
13ec0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
13ed0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
13ee0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13ef0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
13f00 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c       22   /* NUL
13f10 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
13f20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
13f30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
13f40 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
13f50 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
13f60 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
13f70 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
13f80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
13f90 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
13fa0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
13fb0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
13fc0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
13fe0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
13ff0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
14000 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
14010 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
14020 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
14030 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
14040 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
14050 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
14060 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
14070 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
14080 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
14090 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
140a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
140b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
140c0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
140d0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
140e0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
140f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
14100 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
14110 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
14120 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
14130 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
14140 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
14150 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
14160 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
14170 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
14180 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
14190 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
141a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
141b0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
141c0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
141d0 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d   /* Function Nam
141e0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
141f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
14200 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
14210 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
14220 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
14230 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
14240 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
14250 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
14260 74 69 6f 6e 73 20 7b 46 31 32 32 38 30 7d 0a 2a  tions {F12280}.*
14270 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
14280 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
14290 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
142a0 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
142b0 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
142c0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
142d0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
142e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
142f0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
14300 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
14310 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
14320 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
14330 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
14340 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
14350 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
14360 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
14370 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
14380 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
14390 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20  returns a UTF-8 
143a0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
143b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
143c0 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74  ext.** as the st
143d0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
143e0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20  gins executing. 
143f0 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c   Additional call
14400 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61  backs occur.** a
14410 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
14420 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
14430 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
14440 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
14450 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
14460 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
14470 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
14480 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a  es the trigger..
14490 2a 2a 20 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  ** .** The callb
144a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
144b0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
144c0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
144d0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
144e0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
144f0 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20   finishes.  The 
14500 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
14510 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
14520 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
14530 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
14540 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
14550 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
14560 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
14570 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
14580 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  o run..**.** The
14590 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
145a0 28 29 20 41 50 49 20 69 73 20 63 75 72 72 65 6e  () API is curren
145b0 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65  tly considered e
145c0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a  xperimental and.
145d0 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  ** is subject to
145e0 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76   change or remov
145f0 61 6c 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  al in a future r
14600 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  elease..**.** Th
14610 65 20 74 72 69 67 67 65 72 20 72 65 70 6f 72 74  e trigger report
14620 69 6e 67 20 66 65 61 74 75 72 65 20 6f 66 20 74  ing feature of t
14630 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
14640 6b 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 0a  k is considered.
14650 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ** experimental 
14660 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74  and is subject t
14670 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f  o change or remo
14680 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65  val in future re
14690 6c 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74 75 72  leases..** Futur
146a0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
146b0 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
146c0 61 64 64 20 6e 65 77 20 74 72 61 63 65 20 63 61  add new trace ca
146d0 6c 6c 62 61 63 6b 20 0a 2a 2a 20 69 6e 76 6f 63  llback .** invoc
146e0 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ations..**.** IN
146f0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
14700 7b 46 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c  {F12281} The cal
14710 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
14720 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71  egistered by [sq
14730 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 69  lite3_trace()] i
14740 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  s.**          wh
14750 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73 74  enever an SQL st
14760 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
14770 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65 20  gins to execute 
14780 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
14790 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67 67  whenever a trigg
147a0 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66 69  er subprogram fi
147b0 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72 75  rst begins to ru
147c0 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 32  n..**.** {F12282
147d0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
147e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
147f0 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20 70   overrides the p
14800 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20  reviously.**    
14810 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
14820 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e   trace callback.
14830 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 33 7d 20  .**.** {F12283} 
14840 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c  A NULL trace cal
14850 6c 62 61 63 6b 20 64 69 73 61 62 6c 65 73 20 74  lback disables t
14860 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  racing..**.** {F
14870 31 32 32 38 34 7d 20 54 68 65 20 66 69 72 73 74  12284} The first
14880 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
14890 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
148a0 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  is a copy of.** 
148b0 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f 69           the poi
148c0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
148d0 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
148e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
148f0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  e()]..**.** {F12
14900 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  285} The second 
14910 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
14920 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
14930 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
14940 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
14950 55 54 46 38 20 73 74 72 69 6e 67 20 63 6f 6e 74  UTF8 string cont
14960 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 69  aining the origi
14970 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 20  nal text.**     
14980 20 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c 20       of the SQL 
14990 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20  statement as it 
149a0 77 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20  was passed into 
149b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
149c0 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  _v2()].**       
149d0 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61     or the equiva
149e0 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20  lent, or an SQL 
149f0 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 69  comment indicati
14a00 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  ng the beginning
14a10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
14a20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f  a trigger subpro
14a30 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  gram..**.** {F12
14a40 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63  287} The callbac
14a50 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
14a60 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65  tered by [sqlite
14a70 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 20  3_profile()] is 
14a80 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20  invoked.**      
14a90 20 20 20 20 61 73 20 65 61 63 68 20 53 51 4c 20      as each SQL 
14aa0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
14ab0 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  es..**.** {F1228
14ac0 38 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72  8} The first par
14ad0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
14ae0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69  ofile callback i
14af0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20  s a copy of.**  
14b00 20 20 20 20 20 20 20 20 74 68 65 20 33 72 64 20          the 3rd 
14b10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
14b20 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
14b30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 39 7d  ..**.** {F12289}
14b40 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
14b50 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f  meter to the pro
14b60 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  file callback is
14b70 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a   a.**          z
14b80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
14b90 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74  TF-8 string that
14ba0 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f   contains the co
14bb0 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a  mplete text of.*
14bc0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 53  *          the S
14bd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
14be0 69 74 20 77 61 73 20 70 72 6f 63 65 73 73 65 64  it was processed
14bf0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
14c00 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20  pare_v2()].**   
14c10 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71         or the eq
14c20 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  uivalent..**.** 
14c30 7b 46 31 32 32 39 30 7d 20 54 68 65 20 74 68 69  {F12290} The thi
14c40 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
14c50 74 68 65 20 70 72 6f 66 69 6c 65 20 20 63 61 6c  the profile  cal
14c60 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69  lback is an esti
14c70 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  mate.**         
14c80 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
14c90 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66  f nanoseconds of
14ca0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
14cb0 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20   required to.** 
14cc0 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68 65           run the
14cd0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
14ce0 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e  rom start to fin
14cf0 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ish..*/.void *sq
14d00 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
14d10 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
14d20 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
14d30 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
14d40 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
14d50 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
14d60 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
14d70 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
14d80 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
14d90 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
14da0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
14db0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
14dc0 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 31 30 7d  llbacks {F12910}
14dd0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
14de0 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61  ine configures a
14df0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
14e00 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67  on - the.** prog
14e10 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20  ress callback - 
14e20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
14e30 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
14e40 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e  ing long.** runn
14e50 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ing calls to [sq
14e60 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
14e70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
14e80 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
14e90 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 20  get_table()].   
14ea0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
14eb0 6f 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74 65  or this .** inte
14ec0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
14ed0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
14ee0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
14ef0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ery..**.** If th
14f00 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
14f10 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
14f20 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
14f30 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
14f40 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
14f50 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
14f60 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
14f70 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
14f80 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c  on on a GUI dial
14f90 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e  og box..**.** IN
14fa0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
14fb0 7b 46 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c  {F12911} The cal
14fc0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
14fd0 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71  egistered by [sq
14fe0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
14ff0 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20  andler()].**    
15000 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
15010 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
15020 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
15030 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20  g calls to.**   
15040 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
15050 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  step()]..**.** {
15060 46 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67  F12912} The prog
15070 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73  ress callback is
15080 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
15090 72 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61  r every N virtua
150a0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61  l.**          ma
150b0 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77  chine opcodes, w
150c0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
150d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
150e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68   .**          th
150f0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  e [sqlite3_progr
15100 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63  ess_handler()] c
15110 61 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74 65  all that registe
15120 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
15130 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 3c  the callback.  <
15140 74 6f 64 6f 3e 57 68 61 74 20 69 66 20 4e 20 69  todo>What if N i
15150 73 20 6c 65 73 73 20 74 68 61 6e 20 31 3f 3c 2f  s less than 1?</
15160 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  todo>.**.** {F12
15170 39 31 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73  913} The progres
15180 73 20 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c  s callback itsel
15190 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20  f is identified 
151a0 62 79 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  by the third.** 
151b0 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e           argumen
151c0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
151d0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
151e0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 34  ]..**.** {F12914
151f0 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  } The fourth arg
15200 75 6d 65 6e 74 20 5b 73 71 6c 69 74 65 33 5f 70  ument [sqlite3_p
15210 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
15220 29 5d 20 69 73 20 61 0a 2a 2a 2a 20 20 20 20 20  )] is a.***     
15230 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72      void pointer
15240 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 70   passed to the p
15250 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
15260 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
15270 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20  ction each time 
15280 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  it is invoked..*
15290 2a 0a 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49 66  *.** {F12915} If
152a0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
152b0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75  te3_step()] resu
152c0 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61  lts in fewer tha
152d0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20  n.**          N 
152e0 6f 70 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78  opcodes being ex
152f0 65 63 75 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  ecuted,.**      
15300 20 20 20 20 74 68 65 6e 20 74 68 65 20 70 72 6f      then the pro
15310 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
15320 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e  s never invoked.
15330 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46   {END}.** .** {F
15340 31 32 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c  12916} Every cal
15350 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  l to [sqlite3_pr
15360 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
15370 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76  ].**          ov
15380 65 72 77 72 69 74 65 73 20 61 6e 79 20 70 72 65  erwrites any pre
15390 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
153a0 65 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ed progress hand
153b0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ler..**.** {F129
153c0 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72  17} If the progr
153d0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
153e0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65  back is NULL the
153f0 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a  n no progress.**
15400 20 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65            handle
15410 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  r is invoked..**
15420 0a 2a 2a 20 7b 46 31 32 39 31 38 7d 20 49 66 20  .** {F12918} If 
15430 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
15440 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20  lback returns a 
15450 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61  result other tha
15460 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  n 0, then.**    
15470 20 20 20 20 20 20 74 68 65 20 62 65 68 61 76 69        the behavi
15480 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69  or is a if [sqli
15490 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
154a0 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64   had been called
154b0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
154c0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
154d0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
154e0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
154f0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
15500 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
15510 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
15520 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31 32   Connection {F12
15530 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  700}.**.** These
15540 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
15550 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
15560 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d  e file whose nam
15570 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20 62 79  e.** is given by
15580 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
15590 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 66  gument..** The f
155a0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
155b0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
155c0 61 73 20 55 54 46 2d 38 0a 2a 2a 20 66 6f 72 20  as UTF-8.** for 
155d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
155e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
155f0 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20  en_v2()] and as 
15600 55 54 46 2d 31 36 0a 2a 2a 20 69 6e 20 74 68 65  UTF-16.** in the
15610 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
15620 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  er for [sqlite3_
15630 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41 6e  open16()]..** An
15640 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64   [sqlite3*] hand
15650 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 20 72 65  le is usually re
15660 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
15670 20 65 76 65 6e 0a 2a 2a 20 69 66 20 61 6e 20 65   even.** if an e
15680 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
15690 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
156a0 20 69 73 20 69 66 20 53 51 4c 69 74 65 20 69 73   is if SQLite is
156b0 20 75 6e 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c   unable.** to al
156c0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
156d0 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
156e0 65 33 5d 20 6f 62 6a 65 63 74 2c 20 61 20 4e 55  e3] object, a NU
156f0 4c 4c 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 77 72  LL will.** be wr
15700 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
15710 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
15720 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
15730 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
15740 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
15750 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
15760 2f 6f 72 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  /or created).** 
15770 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
15780 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  en [SQLITE_OK] i
15790 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
157a0 65 72 77 69 73 65 20 61 6e 0a 2a 2a 20 65 72 72  erwise an.** err
157b0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
157c0 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ned.  The.** [sq
157d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
157e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
157f0 73 67 31 36 28 29 5d 20 20 72 6f 75 74 69 6e 65  sg16()]  routine
15800 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
15810 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
15820 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
15830 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
15840 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  e error..**.** T
15850 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
15860 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
15870 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
15880 2d 38 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  -8 if.** [sqlite
15890 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71  3_open()] or [sq
158a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
158b0 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
158c0 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
158d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
158e0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
158f0 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2e  en16()] is used.
15900 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
15910 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
15920 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
15930 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
15940 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
15950 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
15960 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  e3*] handle shou
15970 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
15980 79 20 70 61 73 73 69 6e 67 20 69 74 0a 2a 2a 20  y passing it.** 
15990 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
159a0 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
159b0 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
159c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  ed..**.** The [s
159d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
159e0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ] interface work
159f0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
15a00 6f 70 65 6e 28 29 5d 20 0a 2a 2a 20 65 78 63 65  open()] .** exce
15a10 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
15a20 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
15a30 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
15a40 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
15a50 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
15a60 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
15a70 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c  nection.  The fl
15a80 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61  ags parameter ca
15a90 6e 20 62 65 0a 2a 2a 20 6f 6e 65 20 6f 66 3a 0a  n be.** one of:.
15aa0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
15ab0 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
15ac0 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c  _READONLY].** <l
15ad0 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
15ae0 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a 2a 20 3c  _READWRITE].** <
15af0 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
15b00 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
15b10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
15b20 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  TE].** </ol>.**.
15b30 2a 2a 20 54 68 65 20 66 69 72 73 74 20 76 61 6c  ** The first val
15b40 75 65 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74  ue opens the dat
15b50 61 62 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  abase read-only.
15b60 20 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61   .** If the data
15b70 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 20 70 72  base does not pr
15b80 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20  eviously exist, 
15b90 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
15ba0 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  rned..** The sec
15bb0 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73  ond option opens
15bc0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
15bd0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
15be0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
15bf0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
15c00 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69 66 20 74   only if.** if t
15c10 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
15c20 20 70 72 6f 74 65 63 74 65 64 2e 20 20 49 6e 20   protected.  In 
15c30 65 69 74 68 65 72 20 63 61 73 65 20 74 68 65 20  either case the 
15c40 64 61 74 61 62 61 73 65 0a 2a 2a 20 6d 75 73 74  database.** must
15c50 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 20 6f   already exist o
15c60 72 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  r an error is re
15c70 74 75 72 6e 65 64 2e 20 20 54 68 65 20 74 68 69  turned.  The thi
15c80 72 64 20 6f 70 74 69 6f 6e 0a 2a 2a 20 6f 70 65  rd option.** ope
15c90 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ns the database 
15ca0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
15cb0 77 72 69 74 69 6e 67 20 61 6e 64 20 63 72 65 61  writing and crea
15cc0 74 65 73 20 69 74 20 69 66 20 69 74 20 64 6f 65  tes it if it doe
15cd0 73 0a 2a 2a 20 6e 6f 74 20 61 6c 72 65 61 64 79  s.** not already
15ce0 20 65 78 69 73 74 2e 0a 2a 2a 20 54 68 65 20 74   exist..** The t
15cf0 68 69 72 64 20 6f 70 74 69 6f 6e 73 20 69 73 20  hird options is 
15d00 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
15d10 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
15d20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
15d30 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
15d40 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a  3_open16()]..**.
15d50 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
15d60 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
15d70 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
15d80 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
15d90 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
15da0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 74 68 65   shown above the
15db0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
15dc0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
15dd0 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  ** If the filena
15de0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
15df0 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74  , then an privat
15e00 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  e.** in-memory d
15e10 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74  atabase is creat
15e20 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
15e30 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d  ction.  This in-
15e40 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61 74 61 62 61  memory.** databa
15e50 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
15e60 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
15e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
15e80 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  losed.  Future.*
15e90 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
15ea0 69 74 65 20 6d 69 67 68 74 20 6d 61 6b 65 20 75  ite might make u
15eb0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
15ec0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
15ed0 65 73 0a 2a 2a 20 74 68 61 74 20 62 65 67 69 6e  es.** that begin
15ee0 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
15ef0 61 72 61 63 74 65 72 2e 20 20 49 74 20 69 73 20  aracter.  It is 
15f00 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
15f10 20 0a 2a 2a 20 77 68 65 6e 20 61 20 64 61 74 61   .** when a data
15f20 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 72 65  base filename re
15f30 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
15f40 77 69 74 68 0a 2a 2a 20 22 3a 22 20 74 68 61 74  with.** ":" that
15f50 20 79 6f 75 20 70 72 65 66 69 78 20 74 68 65 20   you prefix the 
15f60 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
15f70 70 61 74 68 6e 61 6d 65 20 6c 69 6b 65 20 22 2e  pathname like ".
15f80 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f 69 64 20 61  /" to.** avoid a
15f90 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
15fa0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
15fb0 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
15fc0 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
15fd0 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  te temporary.** 
15fe0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
15ff0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
16000 2e 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20  .  This private 
16010 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
16020 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
16030 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
16040 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
16050 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
16060 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
16070 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
16080 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
16090 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
160a0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
160b0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
160c0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
160d0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
160e0 73 74 65 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61  stem .** interfa
160f0 63 65 20 74 68 61 74 20 74 68 65 20 6e 65 77 20  ce that the new 
16100 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16110 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
16120 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
16130 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
16140 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
16150 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
16160 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20  sqlite3_vfs].** 
16170 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
16180 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
16190 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
161a0 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
161b0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
161c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
161d0 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  .** of [sqlite3_
161e0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  open()] and [sql
161f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
16200 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
16210 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
16220 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
16230 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
16240 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
16250 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
16260 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
16270 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
16280 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
16290 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
162a0 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
162b0 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71  3_open()] or [sq
162c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
162d0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
162e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  TS:.**.** {F1270
162f0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
16300 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
16310 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
16320 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
16330 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
16340 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65 61   interfaces crea
16350 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  te a new.**     
16360 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
16370 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63  onnection] assoc
16380 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20  iated with.**   
16390 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61 62         the datab
163a0 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69  ase file given i
163b0 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70 61  n their first pa
163c0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
163d0 46 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65  F12702} The file
163e0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
163f0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
16400 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20  UTF-8.**        
16410 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f    for [sqlite3_o
16420 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  pen()] and [sqli
16430 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61  te3_open_v2()] a
16440 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20  nd as UTF-16.** 
16450 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20           in the 
16460 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
16470 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  r for [sqlite3_o
16480 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  pen16()]..**.** 
16490 7b 46 31 32 37 30 33 7d 20 41 20 73 75 63 63 65  {F12703} A succe
164a0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
164b0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   of [sqlite3_ope
164c0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
164d0 70 65 6e 31 36 28 29 5d 2c 20 0a 2a 2a 20 20 20  pen16()], .**   
164e0 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
164f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72  e3_open_v2()] wr
16500 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ites a pointer t
16510 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  o a new.**      
16520 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
16530 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a  nnection] into *
16540 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ppDb..**.** {F12
16550 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  704} The [sqlite
16560 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
16570 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
16580 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
16590 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
165a0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  )] interfaces re
165b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
165c0 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a   upon success,.*
165d0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e  *          or an
165e0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
165f0 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69  ror code] on fai
16600 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  lure..**.** {F12
16610 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74  706} The default
16620 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66   text encoding f
16630 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  or a new databas
16640 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  e created using.
16650 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
16660 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
16670 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
16680 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
16690 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 37  8..**.** {F12707
166a0 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65  } The default te
166b0 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  xt encoding for 
166c0 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  a new database c
166d0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
166e0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
166f0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c  3_open16()] will
16700 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a   be UTF-16..**.*
16710 2a 20 7b 46 31 32 37 30 39 7d 20 54 68 65 20 5b  * {F12709} The [
16720 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44  sqlite3_open(F,D
16730 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
16740 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a  equivalent to.**
16750 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
16760 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
16770 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47  ,0)] where the G
16780 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
16790 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
167a0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
167b0 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ]|[SQLITE_OPEN_C
167c0 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  REATE]..**.** {F
167d0 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20  12711} If the G 
167e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
167f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
16800 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73  D,G,V)] contains
16810 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
16820 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
16830 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
16840 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  ] then the datab
16850 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a  ase is opened.**
16860 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65            for re
16870 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ading only..**.*
16880 2a 20 7b 46 31 32 37 31 32 7d 20 49 66 20 74 68  * {F12712} If th
16890 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
168a0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
168b0 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
168c0 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
168d0 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
168e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
168f0 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20  WRITE] then the 
16900 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
16910 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ed.**          r
16920 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
16930 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
16940 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f  or for reading o
16950 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20  nly if the.**   
16960 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77         file is w
16970 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
16980 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
16990 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  system..**.** {F
169a0 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20  12713} If the G 
169b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
169c0 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c  lite3_open(v2(F,
169d0 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68  D,G,V)] omits th
169e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
169f0 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
16a00 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
16a10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
16a20 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
16a30 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
16a40 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
16a50 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
16a60 20 7b 46 31 32 37 31 34 7d 20 49 66 20 74 68 65   {F12714} If the
16a70 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
16a80 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32  [sqlite3_open(v2
16a90 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
16aa0 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
16ab0 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
16ac0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
16ad0 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  E] and the datab
16ae0 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
16af0 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75           previou
16b00 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20  sly exist, then 
16b10 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
16b20 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64  de to create and
16b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69  .**          ini
16b40 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61  tialize the data
16b50 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  base..**.** {F12
16b60 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65  717} If the file
16b70 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  name argument to
16b80 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
16b90 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
16ba0 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
16bb0 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
16bc0 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d  pen_v2()] is ":m
16bd0 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e  emory:", then an
16be0 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20   private,.**    
16bf0 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c        ephemeral,
16c00 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
16c10 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66  ase is created f
16c20 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
16c30 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  n..**          <
16c40 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f  todo>Is SQLITE_O
16c50 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54  PEN_CREATE|SQLIT
16c60 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
16c70 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20   required.**    
16c80 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33        in sqlite3
16c90 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64  _open_v2()?</tod
16ca0 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 39  o>.**.** {F12719
16cb0 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  } If the filenam
16cc0 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  e is NULL or an 
16cd0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
16ce0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a  en a private,.**
16cf0 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
16d00 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  ral on-disk data
16d10 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
16d20 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20  ated..**        
16d30 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54    <todo>Is SQLIT
16d40 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51  E_OPEN_CREATE|SQ
16d50 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
16d60 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20  ITE required.** 
16d70 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69           in sqli
16d80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f  te3_open_v2()?</
16d90 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  todo>.**.** {F12
16da0 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61  721} The [databa
16db0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
16dc0 72 65 61 74 65 64 20 62 79 20 0a 2a 2a 20 20 20  reated by .**   
16dd0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16de0 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
16df0 5d 20 77 69 6c 6c 20 75 73 65 20 74 68 65 0a 2a  ] will use the.*
16e00 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
16e10 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
16e20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
16e30 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  e V parameter, o
16e40 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
16e50 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
16e60 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
16e70 73 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  s V is a NULL po
16e80 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  inter..**.** {F1
16e90 32 37 32 33 7d 20 54 77 6f 20 5b 64 61 74 61 62  2723} Two [datab
16ea0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
16eb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16ec0 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72  tions] will shar
16ed0 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65  e a common cache
16ee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
16ef0 62 6f 74 68 20 77 65 72 65 20 6f 70 65 6e 65 64  both were opened
16f00 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 56   with the same V
16f10 46 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  FS.**          w
16f20 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e  hile [sqlite3_en
16f30 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
16f40 65 20 7c 20 73 68 61 72 65 64 20 63 61 63 68 65  e | shared cache
16f50 20 6d 6f 64 65 20 77 61 73 20 65 6e 61 62 6c 65   mode was enable
16f60 64 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  d] and.**       
16f70 20 20 20 69 66 20 62 6f 74 68 20 66 69 6c 65 6e     if both filen
16f80 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 65 71 75  ames compare equ
16f90 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28  al using memcmp(
16fa0 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 66  ).**          af
16fb0 74 65 72 20 68 61 76 69 6e 67 20 62 65 65 6e 20  ter having been 
16fc0 70 72 6f 63 65 73 73 65 64 20 62 79 20 74 68 65  processed by the
16fd0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
16fe0 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d  xFullPathname] m
16ff0 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 20 20 20 20  ethod of.**     
17000 20 20 20 20 20 74 68 65 20 56 46 53 2e 0a 2a 2a       the VFS..**
17010 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
17020 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
17030 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
17040 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
17050 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
17060 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
17070 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
17080 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
17090 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
170a0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
170b0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
170c0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
170d0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
170e0 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
170f0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
17100 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
17110 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
17120 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
17130 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
17140 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
17150 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
17160 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
17170 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
17180 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
17190 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
171a0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
171b0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
171c0 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
171d0 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
171e0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
171f0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
17200 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
17210 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
17220 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
17230 65 73 20 7b 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a  es {F12800}.**.*
17240 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72  * The sqlite3_er
17250 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
17260 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
17270 6d 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45  meric.** [SQLITE
17280 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
17290 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  e] or [SQLITE_IO
172a0 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
172b0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
172c0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  .** for the most
172d0 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
172e0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
172f0 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  l associated.** 
17300 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5d 20 68  with [sqlite3] h
17310 61 6e 64 6c 65 20 27 64 62 27 2e 20 49 66 20 61  andle 'db'. If a
17320 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
17330 66 61 69 6c 65 64 20 62 75 74 20 74 68 65 0a 2a  failed but the.*
17340 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  * most recent AP
17350 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
17360 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
17370 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
17380 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20  errcode().** is 
17390 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
173a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   The sqlite3_err
173b0 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
173c0 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
173d0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
173e0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
173f0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
17400 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
17410 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 72   UTF8 or UTF16 r
17420 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
17430 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
17440 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
17450 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
17460 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
17470 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
17480 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
17490 74 6f 20 77 6f 72 72 79 20 77 69 74 68 20 66 72  to worry with fr
174a0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
174b0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
174c0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
174d0 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
174e0 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
174f0 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
17500 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
17510 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
17520 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ace functions..*
17530 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
17540 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 31 7d 20  .**.** {F12801} 
17550 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  The [sqlite3_err
17560 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61  code(D)] interfa
17570 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
17580 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20  umeric.**       
17590 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20     [SQLITE_OK | 
175a0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
175b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
175c0 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
175d0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
175e0 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20   code].**       
175f0 20 20 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20     for the most 
17600 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20  recently failed 
17610 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61  interface call a
17620 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20  ssociated.**    
17630 20 20 20 20 20 20 77 69 74 68 20 5b 64 61 74 61        with [data
17640 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17650 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30   D..**.** {F1280
17660 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
17670 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b  errmsg(D)] and [
17680 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
17690 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (D)].**         
176a0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
176b0 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
176c0 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64 65  age text that de
176d0 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20 20  scribes.**      
176e0 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69 6e      the error in
176f0 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63 65   the mostly rece
17700 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65  ntly failed inte
17710 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20  rface call,.**  
17720 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64 20          encoded 
17730 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20 6f  as either UTF8 o
17740 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74 69  r UTF16 respecti
17750 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  vely..**.** {F12
17760 38 30 37 7d 20 54 68 65 20 73 74 72 69 6e 67 73  807} The strings
17770 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
17780 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
17790 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
177a0 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  msg16()].**     
177b0 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 75       are valid u
177c0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 53 51  ntil the next SQ
177d0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 63  Lite interface c
177e0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  all..**.** {F128
177f0 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50 49  08} Calls to API
17800 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64   routines that d
17810 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e 20  o not return an 
17820 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
17830 20 20 20 20 20 20 20 28 65 78 61 6d 70 6c 65 3a         (example:
17840 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
17850 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a  ount()]) do not.
17860 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 6e  **          chan
17870 67 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ge the error cod
17880 65 20 6f 72 20 6d 65 73 73 61 67 65 20 72 65 74  e or message ret
17890 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
178a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
178b0 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74  rcode()], [sqlit
178c0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72  e3_errmsg()], or
178d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
178e0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  16()]..**.** {F1
178f0 32 38 30 39 7d 20 49 6e 74 65 72 66 61 63 65 73  2809} Interfaces
17900 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20 61 73   that are not as
17910 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
17920 73 70 65 63 69 66 69 63 0a 2a 2a 20 20 20 20 20  specific.**     
17930 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
17940 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d  onnection] (exam
17950 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20  ples:.**        
17960 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e    [sqlite3_mprin
17970 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  tf()] or [sqlite
17980 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
17990 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20  cache()].**     
179a0 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e       do not chan
179b0 67 65 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  ge the values re
179c0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
179d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
179e0 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69  rrcode()], [sqli
179f0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f  te3_errmsg()], o
17a00 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
17a10 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  g16()]..*/.int s
17a20 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
17a30 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
17a40 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
17a50 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
17a60 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
17a70 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
17a80 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
17a90 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
17aa0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
17ab0 20 7b 46 31 33 30 30 30 7d 0a 2a 2a 20 4b 45 59   {F13000}.** KEY
17ac0 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
17ad0 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
17ae0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
17af0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
17b00 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
17b10 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
17b20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
17b30 6d 65 6e 74 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ment.  This.** o
17b40 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
17b50 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
17b60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
17b70 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63 6f 6d  t" or a .** "com
17b80 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
17b90 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
17ba0 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
17bb0 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69 66 65  .** .** The life
17bc0 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20   of a statement 
17bd0 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65  object goes some
17be0 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a  thing like this:
17bf0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
17c00 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f  li> Create the o
17c10 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
17c20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17c30 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a  )] or a related.
17c40 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e  **      function
17c50 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
17c60 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
17c70 72 61 6d 65 74 65 72 73 20 75 73 69 6e 67 0a 2a  rameters using.*
17c80 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f  *      [sqlite3_
17c90 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
17ca0 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74 65 72  te3_bind_* inter
17cb0 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  faces]..** <li> 
17cc0 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
17cd0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
17ce0 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
17cf0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
17d00 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
17d10 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
17d20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
17d30 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
17d40 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
17d50 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
17d60 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
17d70 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
17d80 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
17d90 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
17da0 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
17db0 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
17dc0 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
17dd0 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
17de0 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
17df0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
17e00 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
17e10 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
17e20 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
17e30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17e40 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
17e50 73 20 7b 46 31 32 37 36 30 7d 0a 2a 2a 0a 2a 2a  s {F12760}.**.**
17e60 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
17e70 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
17e80 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
17e90 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
17ea0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
17eb0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
17ec0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
17ed0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
17ee0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
17ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17f00 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
17f10 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
17f20 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
17f30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
17f40 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
17f50 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
17f60 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
17f70 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
17f80 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
17f90 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
17fa0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
17fb0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
17fc0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
17fd0 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74  ruct.  The funct
17fe0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
17ff0 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a  old limit..**.**
18000 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69   If the new limi
18010 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
18020 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
18030 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
18040 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74  ** For the limit
18050 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c   category of SQL
18060 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68  ITE_LIMIT_XYZ th
18070 65 72 65 20 69 73 20 61 20 68 61 72 64 20 75 70  ere is a hard up
18080 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74  per.** bound set
18090 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69   by a compile-ti
180a0 6d 65 20 43 2d 70 72 65 70 72 6f 63 65 73 73 20  me C-preprocess 
180b0 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49  macro named SQLI
180c0 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28  TE_MAX_XYZ..** (
180d0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
180e0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
180f0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
18100 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f  ).** Attempts to
18110 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
18120 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
18130 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
18140 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
18150 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
18160 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a  rd upper limit..
18170 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c  **.** Run time l
18180 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
18190 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
181a0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
181b0 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
181c0 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
181d0 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
181e0 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
181f0 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
18200 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
18210 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
18220 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
18230 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
18240 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f  t be a.** webbro
18250 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
18260 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
18270 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
18280 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
18290 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
182a0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
182b0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
182c0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
182d0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
182e0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
182f0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
18300 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
18310 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
18320 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
18330 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
18340 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
18350 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
18360 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
18370 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
18380 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
18390 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
183a0 61 63 68 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ach.  Developers
183b0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
183c0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
183d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
183e0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
183f0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
18400 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
18410 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
18420 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
18430 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
18440 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
18450 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
18460 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
18470 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
18480 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
18490 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
184a0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
184b0 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
184c0 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a  ntal and is subj
184d0 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61 6e 67 65  ect.** to change
184e0 20 6f 72 20 72 65 6d 6f 76 61 6c 20 77 69 74 68   or removal with
184f0 6f 75 74 20 70 72 69 6f 72 20 6e 6f 74 69 63 65  out prior notice
18500 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
18510 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36  TS:.**.** {F1276
18520 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  2} A successful 
18530 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
18540 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77  _limit(D,C,V)] w
18550 68 65 72 65 20 56 20 69 73 0a 2a 2a 20 20 20 20  here V is.**    
18560 20 20 20 20 20 20 70 6f 73 69 74 69 76 65 20 63        positive c
18570 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
18580 20 20 20 20 20 20 20 6c 69 6d 69 74 20 6f 6e 20         limit on 
18590 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73  the size of cons
185a0 74 72 75 63 74 20 43 20 69 6e 20 5b 64 61 74 61  truct C in [data
185b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
185c0 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74   D.**          t
185d0 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20  o the lesser of 
185e0 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 20 75  V and the hard u
185f0 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68  pper bound on th
18600 65 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20  e size.**       
18610 20 20 20 6f 66 20 43 20 74 68 61 74 20 69 73 20     of C that is 
18620 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
18630 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  ime..**.** {F127
18640 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  66} A successful
18650 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
18660 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
18670 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61 74  where V is negat
18680 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
18690 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 74 65  leaves the state
186a0 20 6f 66 20 5b 64 61 74 61 62 61 73 65 20 63 6f   of [database co
186b0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63 68  nnection] D unch
186c0 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  anged..**.** {F1
186d0 32 37 36 39 7d 20 41 20 73 75 63 63 65 73 73 66  2769} A successf
186e0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
186f0 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
18700 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  ] returns the.**
18710 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
18720 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20  of the limit on 
18730 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73  the size of cons
18740 74 72 75 63 74 20 43 20 69 6e 0a 2a 2a 20 20 20  truct C in.**   
18750 20 20 20 20 20 20 20 69 6e 20 5b 64 61 74 61 62         in [datab
18760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
18770 44 20 61 73 20 69 74 20 77 61 73 20 70 72 69 6f  D as it was prio
18780 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a 2a  r to the call..*
18790 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
187a0 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
187b0 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
187c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
187d0 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
187e0 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b 46  it Categories {F
187f0 31 32 37 39 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  12790}.** KEYWOR
18800 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
18810 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65  ory} {limit cate
18820 67 6f 72 69 65 73 7d 0a 2a 2a 20 0a 2a 2a 20 54  gories}.** .** T
18830 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
18840 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73  efine various as
18850 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61  pects of a [data
18860 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18870 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
18880 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20  limited in size 
18890 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  by calls to [sql
188a0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
188b0 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  * The meanings o
188c0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
188d0 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c  mits are as foll
188e0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ows:.**.** <dl>.
188f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
18900 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
18910 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
18920 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 0a 2a  um size of any.*
18930 2a 20 73 74 72 69 6e 67 20 6f 72 20 62 6c 6f 62  * string or blob
18940 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64   or table row.<d
18950 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18960 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
18970 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
18980 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
18990 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
189a0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a  atement.</dd>.**
189b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
189c0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
189d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
189e0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
189f0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
18a00 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
18a10 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
18a20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20  set of a SELECT 
18a30 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
18a40 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
18a50 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
18a60 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
18a70 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
18a80 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ause.</dd>.**.**
18a90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18aa0 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
18ab0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
18ac0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
18ad0 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
18ae0 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
18af0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
18b00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
18b10 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
18b20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
18b30 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
18b40 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
18b50 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
18b60 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  nt.</dd>.**.** <
18b70 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
18b80 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
18b90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18ba0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
18bb0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
18bc0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
18bd0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
18be0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
18bf0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
18c00 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18c10 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
18c20 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
18c30 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
18c40 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
18c50 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
18c60 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18c70 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
18c80 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
18c90 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
18ca0 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64  er of attached d
18cb0 61 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a  atabases.</dd>.*
18cc0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18cd0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
18ce0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
18cf0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
18d00 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
18d10 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
18d20 20 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a   to the LIKE or.
18d30 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72  ** GLOB operator
18d40 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
18d50 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
18d60 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
18d70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18d80 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18d90 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e   variables in an
18da0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
18db0 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f  hat can.** be bo
18dc0 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  und.</dd>.** </d
18dd0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
18de0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
18df0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
18e00 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
18e10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
18e20 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
18e30 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
18e40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
18e50 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
18e60 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
18e70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
18e80 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
18e90 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
18ea0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
18eb0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
18ec0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
18ed0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
18ee0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
18ef0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
18f00 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
18f10 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
18f20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
18f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
18f40 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
18f50 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
18f60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
18f70 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
18f80 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
18f90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
18fa0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
18fb0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
18fc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18fd0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
18fe0 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  L Statement {F13
18ff0 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  010}.**.** To ex
19000 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
19010 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
19020 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
19030 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
19040 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
19050 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
19060 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  tines. .**.** Th
19070 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19080 20 22 64 62 22 20 69 73 20 61 6e 20 5b 64 61 74   "db" is an [dat
19090 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
190a0 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ] .** obtained f
190b0 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c  rom a prior call
190c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
190d0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
190e0 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20  pen_v2()].** or 
190f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
19100 29 5d 2e 20 0a 2a 2a 20 54 68 65 20 73 65 63 6f  )]. .** The seco
19110 6e 64 20 61 72 67 75 6d 65 6e 74 20 22 7a 53 71  nd argument "zSq
19120 6c 22 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  l" is the statem
19130 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
19140 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
19150 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
19160 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
19170 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
19180 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
19190 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
191a0 65 72 66 61 63 65 73 20 75 73 65 73 20 55 54 46  erfaces uses UTF
191b0 2d 38 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  -8 and sqlite3_p
191c0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
191d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
191e0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
191f0 2d 31 36 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  -16. {END}.**.**
19200 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
19210 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a 2a  gument is less.*
19220 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  * than zero, the
19230 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
19240 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
19250 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
19260 2a 2a 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e  ** If nByte is n
19270 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
19280 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
19290 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  mum number of .*
192a0 2a 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f  * bytes read fro
192b0 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42  m zSql.  When nB
192c0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
192d0 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
192e0 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
192f0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
19300 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
19310 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
19320 20 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74   .** the nByte-t
19330 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
19340 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
19350 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
19360 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
19370 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
19380 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
19390 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
193a0 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
193b0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
193c0 20 74 6f 20 62 65 20 68 61 64 20 62 79 20 70 61   to be had by pa
193d0 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
193e0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 0a 2a  arameter that .*
193f0 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
19400 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
19410 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
19420 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
19430 6e 67 3c 2f 69 3e 20 0a 2a 2a 20 74 68 65 20 6e  ng</i> .** the n
19440 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
19450 74 65 73 2e 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  tes.{END}.**.** 
19460 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
19470 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
19480 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
19490 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a  the end of the.*
194a0 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  * first SQL stat
194b0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
194c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
194d0 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  nly compile the 
194e0 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65  first.** stateme
194f0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
19500 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
19510 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20  ointing to what 
19520 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d  remains.** uncom
19530 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70  piled..**.** *pp
19540 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
19550 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
19560 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
19570 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
19580 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
19590 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
195a0 73 74 65 70 28 29 5d 2e 20 20 4f 72 20 69 66 20  step()].  Or if 
195b0 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
195c0 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 0a 2a 2a  r, *ppStmt is.**
195d0 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49   set to NULL.  I
195e0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
195f0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
19600 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 0a 2a   (if the input.*
19610 2a 20 69 73 20 61 6e 64 20 65 6d 70 74 79 20 73  * is and empty s
19620 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
19630 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
19640 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
19650 0a 2a 2a 20 7b 55 31 33 30 31 38 7d 20 54 68 65  .** {U13018} The
19660 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
19670 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
19680 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
19690 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 53  he.** compiled S
196a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
196b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
196c0 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
196d0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
196e0 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20   with it..**.** 
196f0 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
19700 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
19710 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
19720 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  an .** [error co
19730 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
19740 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
19750 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
19760 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
19770 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
19780 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
19790 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
197a0 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
197b0 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
197c0 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
197d0 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
197e0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
197f0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
19800 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
19810 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32  d..** In the "v2
19820 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
19830 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
19840 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
19850 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
19860 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
19870 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
19880 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20  copy of the .** 
19890 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
198a0 74 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 63 61  t. {END} This ca
198b0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
198c0 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
198d0 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
198e0 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69   a differently i
198f0 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a  n two ways:.**.*
19900 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
19910 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
19920 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
19930 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
19940 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
19950 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
19960 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
19970 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
19980 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
19990 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
199a0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
199b0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
199c0 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20   run it again.  
199d0 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61  If the schema ha
199e0 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20  s changed in.** 
199f0 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  a way that makes
19a00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e   the statement n
19a10 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20  o longer valid, 
19a20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19a30 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72   will still.** r
19a40 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43  eturn [SQLITE_SC
19a50 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69  HEMA].  But unli
19a60 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  ke the legacy be
19a70 68 61 76 69 6f 72 2c 20 0a 2a 2a 20 5b 53 51 4c  havior, .** [SQL
19a80 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 20 6e  ITE_SCHEMA] is n
19a90 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  ow a fatal error
19aa0 2e 20 20 43 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73  .  Calling.** [s
19ab0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19ac0 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20  2()] again will 
19ad0 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20  not make the.** 
19ae0 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20  error go away.  
19af0 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74  Note: use [sqlit
19b00 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20  e3_errmsg()] to 
19b10 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a  find the text.**
19b20 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 20   of the parsing 
19b30 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c  error that resul
19b40 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  ts in an [SQLITE
19b50 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e  _SCHEMA] return.
19b60 20 7b 45 4e 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a   {END}.** </li>.
19b70 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68  **.** <li>.** Wh
19b80 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
19b90 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rs, .** [sqlite3
19ba0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
19bb0 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
19bc0 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20 5b 65 72  detailed .** [er
19bd0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
19be0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
19bf0 64 65 73 5d 2e 20 0a 2a 2a 20 54 68 65 20 6c 65  des]. .** The le
19c00 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
19c10 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
19c20 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
19c30 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
19c40 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  ric.** [SQLITE_E
19c50 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
19c60 65 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20  e and you would 
19c70 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
19c80 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a  econd call to.**
19c90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
19ca0 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
19cb0 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
19cc0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
19cd0 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68  problem..** With
19ce0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
19cf0 65 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  e interfaces, th
19d00 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
19d10 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
19d20 72 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64  r is.** returned
19d30 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
19d40 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
19d50 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
19d60 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 31 7d  :.**.** {F13011}
19d70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
19d80 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e  epare(db,zSql,..
19d90 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  .)] and.**      
19da0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
19db0 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
19dc0 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ...)] interfaces
19dd0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
19de0 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
19df0 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61  in their zSql pa
19e00 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 38  rameter as UTF-8
19e10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 32 7d  ..**.** {F13012}
19e20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
19e30 65 70 61 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c  epare16(db,zSql,
19e40 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ...)] and.**    
19e50 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
19e60 72 65 70 61 72 65 31 36 5f 76 32 28 64 62 2c 7a  repare16_v2(db,z
19e70 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  Sql,...)] interf
19e80 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74  aces interpret t
19e90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
19ea0 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71  ext in their zSq
19eb0 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55  l parameter as U
19ec0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
19ed0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
19ee0 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 33 7d 20 49  **.** {F13013} I
19ef0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
19f00 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
19f10 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
19f20 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a  Sql,nByte,...)].
19f30 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
19f40 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20  its variants is 
19f50 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
19f60 74 68 65 6e 20 53 51 4c 20 74 65 78 74 20 69 73  then SQL text is
19f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61  .**          rea
19f80 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72  d from zSql is r
19f90 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69  ead up to the fi
19fa0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
19fb0 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  tor..**.** {F130
19fc0 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65  14} If the nByte
19fd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
19fe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19ff0 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e  (db,zSql,nByte,.
1a000 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
1a010 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
1a020 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  s is non-negativ
1a030 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73 74 20  e, then at most 
1a040 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
1a050 20 20 20 20 20 20 20 20 20 53 51 4c 20 74 65 78           SQL tex
1a060 74 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  t is read from z
1a070 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  Sql..**.** {F130
1a080 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f  15} In [sqlite3_
1a090 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1a0a0 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20  ql,N,P,pzTail)] 
1a0b0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1a0c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
1a0d0 74 68 65 20 7a 53 71 6c 20 69 6e 70 75 74 20 74  the zSql input t
1a0e0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72  ext contains mor
1a0f0 65 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73  e than one SQL s
1a100 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20  tatement.**     
1a110 20 20 20 20 20 61 6e 64 20 70 7a 54 61 69 6c 20       and pzTail 
1a120 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1a130 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
1a140 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
1a150 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  e.**          fi
1a160 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68  rst byte past th
1a170 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
1a180 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
1a190 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20   in zSql..**    
1a1a0 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74        <todo>What
1a1b0 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f   does *pzTail po
1a1c0 69 6e 74 20 74 6f 20 69 66 20 74 68 65 72 65 20  int to if there 
1a1d0 69 73 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74  is one statement
1a1e0 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b  ?</todo>.**.** {
1a1f0 46 31 33 30 31 36 7d 20 41 20 73 75 63 63 65 73  F13016} A succes
1a200 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1a210 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1a220 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d  (db,zSql,N,ppStm
1a230 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  t,...)].**      
1a240 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74      or one of it
1a250 73 20 76 61 72 69 61 6e 74 73 20 77 72 69 74 65  s variants write
1a260 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61  s into *ppStmt a
1a270 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
1a280 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  w.**          [p
1a290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a2a0 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  t] or a pointer 
1a2b0 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  to NULL.**      
1a2c0 20 20 20 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74      if zSql cont
1a2d0 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68  ains nothing oth
1a2e0 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61  er than whitespa
1a2f0 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 20  ce or comments. 
1a300 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 39 7d 20  .**.** {F13019} 
1a310 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
1a320 70 61 72 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  pare_v2()] inter
1a330 66 61 63 65 20 61 6e 64 20 69 74 73 20 76 61 72  face and its var
1a340 69 61 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20  iants return.** 
1a350 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
1a360 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f  _OK] or an appro
1a370 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
1a380 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72 65  de] upon failure
1a390 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 32 31 7d  ..**.** {F13021}
1a3a0 20 42 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   Before [sqlite3
1a3b0 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c  _prepare(db,zSql
1a3c0 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a  ,nByte,ppStmt,pz
1a3d0 54 61 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a 2a  Tail)] or its.**
1a3e0 20 20 20 20 20 20 20 20 20 20 76 61 72 69 61 6e            varian
1a3f0 74 73 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  ts returns an er
1a400 72 6f 72 20 28 61 6e 79 20 76 61 6c 75 65 20 6f  ror (any value o
1a410 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1a420 45 5f 4f 4b 5d 29 0a 2a 2a 20 20 20 20 20 20 20  E_OK]).**       
1a430 20 20 20 69 74 20 66 69 72 73 74 20 73 65 74 73     it first sets
1a440 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c   *ppStmt to NULL
1a450 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1a460 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
1a470 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1a480 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1a490 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1a4a0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1a4b0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1a4c0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1a4d0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1a4e0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1a4f0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1a500 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1a510 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1a520 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1a530 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1a540 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1a550 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1a560 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1a570 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1a580 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1a590 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1a5a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
1a5b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1a5c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1a5d0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1a5e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1a5f0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1a600 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1a610 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1a620 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1a630 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1a640 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1a650 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1a660 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1a670 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1a680 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1a690 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1a6a0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1a6b0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1a6c0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1a6d0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1a6e0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1a6f0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
1a700 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1a710 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1a720 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1a730 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1a740 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1a750 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1a760 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1a770 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1a780 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1a790 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1a7a0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1a7b0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1a7c0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1a7d0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1a7e0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1a7f0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1a800 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1a810 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1a820 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1a830 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
1a840 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1a850 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1a860 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1a870 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1a880 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1a890 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1a8a0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1a8b0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1a8c0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1a8d0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1a8e0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1a8f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1a900 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1a910 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1a920 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1a930 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1a940 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1a950 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1a960 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
1a970 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20 52 65 74  .** CAPIREF: Ret
1a980 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
1a990 74 20 53 51 4c 20 7b 46 31 33 31 30 30 7d 0a 2a  t SQL {F13100}.*
1a9a0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
1a9b0 61 63 65 20 20 63 61 6e 20 62 65 20 75 73 65 64  ace  can be used
1a9c0 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
1a9d0 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
1a9e0 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
1a9f0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
1aa00 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
1aa10 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 0a   statement]..**.
1aa20 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1aa30 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d 20 49 66  *.** {F13101} If
1aa40 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1aa50 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64  tatement] passed
1aa60 20 61 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   as .**         
1aa70 20 74 68 65 20 61 6e 20 61 72 67 75 6d 65 6e 74   the an argument
1aa80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c   to [sqlite3_sql
1aa90 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ()] was compiled
1aaa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6d  .**          com
1aab0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1aac0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1aad0 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
1aae0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1aaf0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1ab00 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ],.**          t
1ab10 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
1ab20 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ()] function ret
1ab30 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1ab40 6f 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  o a.**          
1ab50 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1ab60 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
1ab70 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  g a UTF-8 render
1ab80 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
1ab90 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  of the original 
1aba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1abb0 2a 0a 2a 2a 20 7b 46 31 33 31 30 32 7d 20 49 66  *.** {F13102} If
1abc0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1abd0 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64  tatement] passed
1abe0 20 61 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   as .**         
1abf0 20 74 68 65 20 61 6e 20 61 72 67 75 6d 65 6e 74   the an argument
1ac00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c   to [sqlite3_sql
1ac10 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ()] was compiled
1ac20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6d  .**          com
1ac30 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1ac40 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1ac50 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  are()] or.**    
1ac60 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
1ac70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20  repare16()],.** 
1ac80 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
1ac90 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 66 75  qlite3_sql()] fu
1aca0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1acb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1acc0 2a 0a 2a 2a 20 7b 46 31 33 31 30 33 7d 20 54 68  *.** {F13103} Th
1acd0 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
1ace0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 71  d by [sqlite3_sq
1acf0 6c 28 53 29 5d 20 69 73 20 76 61 6c 69 64 20 75  l(S)] is valid u
1ad00 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20  ntil the.**     
1ad10 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
1ad20 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 64  tatement] S is d
1ad30 65 6c 65 74 65 64 20 75 73 69 6e 67 20 5b 73 71  eleted using [sq
1ad40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
1ad50 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
1ad60 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
1ad70 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
1ad80 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
1ad90 33 52 45 46 3a 20 20 44 79 6e 61 6d 69 63 61 6c  3REF:  Dynamical
1ada0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
1adb0 62 6a 65 63 74 20 20 7b 46 31 35 30 30 30 7d 0a  bject  {F15000}.
1adc0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1add0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1ade0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
1adf0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1ae00 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
1ae10 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
1ae20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
1ae30 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
1ae40 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
1ae50 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
1ae60 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
1ae70 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
1ae80 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 20 66  dynamic typing f
1ae90 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
1aea0 20 73 74 6f 72 65 73 2e 20 20 0a 2a 2a 20 56 61   stores.  .** Va
1aeb0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
1aec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1aed0 65 63 74 73 20 63 61 6e 20 62 65 0a 2a 2a 20 62  ects can be.** b
1aee0 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
1aef0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
1af00 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
1af10 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
1af20 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
1af30 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
1af40 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
1af50 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
1af60 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
1af70 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
1af80 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
1af90 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
1afa0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
1afb0 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
1afc0 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
1afd0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1afe0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1aff0 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
1b000 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
1b010 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
1b020 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
1b030 65 73 20 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  es .** whether o
1b040 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
1b050 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
1b060 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
1b070 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
1b080 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
1b090 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
1b0a0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
1b0b0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
1b0c0 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e   held.  A intern
1b0d0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
1b0e0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
1b0f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1b100 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
1b110 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1b120 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1b130 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1b140 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
1b150 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1b160 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
1b170 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
1b180 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1b190 45 3d 30 20 61 6e 64 20 77 69 74 68 20 5b 73 71  E=0 and with [sq
1b1a0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1b1b0 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
1b1c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
1b1d0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
1b1e0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 70 72 6f 74   between.** prot
1b1f0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
1b200 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1b210 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
1b220 74 68 65 79 20 63 61 6e 20 62 65 0a 2a 2a 20 75  they can be.** u
1b230 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
1b240 62 6c 65 2e 20 20 48 6f 77 65 76 65 72 2c 20 66  ble.  However, f
1b250 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
1b260 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 0a 2a  portability it.*
1b270 2a 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  * is recommended
1b280 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
1b290 6e 73 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ns make the dist
1b2a0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  inction between.
1b2b0 2a 2a 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  ** between prote
1b2c0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1b2d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1b2e0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
1b2f0 69 66 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 73  if.** they are s
1b300 69 6e 67 6c 65 20 74 68 72 65 61 64 65 64 2e 0a  ingle threaded..
1b310 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1b320 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1b330 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
1b340 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
1b350 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
1b360 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 70 70 6c  entation of appl
1b370 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1b380 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  SQL functions ar
1b390 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
1b3a0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
1b3b0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
1b3c0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
1b3d0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
1b3e0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
1b3f0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
1b400 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1b410 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
1b420 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
1b430 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
1b440 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
1b450 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
1b460 29 5d 2e 20 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  )].  All other.*
1b470 2a 20 69 6e 74 65 72 66 61 63 65 73 20 74 68 61  * interfaces tha
1b480 74 20 75 73 65 20 73 71 6c 69 74 65 33 5f 76 61  t use sqlite3_va
1b490 6c 75 65 20 72 65 71 75 69 72 65 20 70 72 6f 74  lue require prot
1b4a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1b4b0 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
1b4c0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
1b4d0 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
1b4e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b4f0 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  F:  SQL Function
1b500 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20   Context Object 
1b510 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 54  {F16001}.**.** T
1b520 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
1b530 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
1b540 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
1b550 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
1b560 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1b570 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74  object.  A point
1b580 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
1b590 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20 6f 62 6a 65  _context.** obje
1b5a0 63 74 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ct is always fir
1b5b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1b5c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1b5d0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1b5e0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
1b5f0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
1b600 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
1b610 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
1b620 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e 67 20  I3REF:  Binding 
1b630 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
1b640 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 46  ed Statements {F
1b650 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  13500}.**.** In 
1b660 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20  the SQL strings 
1b670 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1b680 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1b690 61 6e 64 20 69 74 73 0a 2a 2a 20 76 61 72 69 61  and its.** varia
1b6a0 6e 74 73 2c 20 6c 69 74 65 72 61 6c 73 20 6d 61  nts, literals ma
1b6b0 79 20 62 65 20 72 65 70 6c 61 63 65 20 62 79 20  y be replace by 
1b6c0 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f  a parameter in o
1b6d0 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 66  ne.** of these f
1b6e0 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  orms:.**.** <ul>
1b6f0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
1b700 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
1b710 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
1b720 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
1b730 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
1b740 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65  ** In the parame
1b750 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20  ter forms shown 
1b760 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20  above NNN is an 
1b770 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
1b780 0a 2a 2a 20 56 56 56 20 61 6c 70 68 61 2d 6e 75  .** VVV alpha-nu
1b790 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20  meric parameter 
1b7a0 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  name..** The val
1b7b0 75 65 73 20 6f 66 20 74 68 65 73 65 20 70 61 72  ues of these par
1b7c0 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
1b7d0 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
1b7e0 65 74 65 72 20 6e 61 6d 65 73 22 0a 2a 2a 20 6f  eter names".** o
1b7f0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
1b800 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
1b810 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
1b820 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1b830 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
1b840 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  re..**.** The fi
1b850 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1b860 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1b870 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 6c  _*() routines al
1b880 77 61 79 73 0a 2a 2a 20 69 73 20 61 20 70 6f 69  ways.** is a poi
1b890 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1b8a0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1b8b0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
1b8c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1b8d0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
1b8e0 20 76 61 72 69 61 6e 74 73 2e 20 54 68 65 20 73   variants. The s
1b8f0 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
1b900 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
1b910 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1b920 74 6f 20 62 65 20 73 65 74 2e 20 54 68 65 0a 2a  to be set. The.*
1b930 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  * first paramete
1b940 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
1b950 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73  f 1.  When the s
1b960 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 70 61 72  ame named.** par
1b970 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
1b980 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
1b990 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
1b9a0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
1b9b0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
1b9c0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
1b9d0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
1b9e0 20 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66   .** The index f
1b9f0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
1ba00 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
1ba10 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
1ba20 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1ba30 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
1ba40 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
1ba50 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20  .  The index.** 
1ba60 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
1ba70 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
1ba80 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68  ue of NNN..** Th
1ba90 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
1baa0 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
1bab0 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  d the compile-ti
1bac0 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  me.** parameter 
1bad0 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41  SQLITE_MAX_VARIA
1bae0 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66 61  BLE_NUMBER (defa
1baf0 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
1bb00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
1bb10 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1bb20 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
1bb30 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
1bb40 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 0a  .**.** In those.
1bb50 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
1bb60 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
1bb70 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
1bb80 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ue is the number
1bb90 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20   of bytes.** in 
1bba0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
1bbb0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
1bbc0 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75   value is the nu
1bbd0 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
1bbe0 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68 65 20 76  </u>.** in the v
1bbf0 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
1bc00 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1bc10 72 73 2e 20 0a 2a 2a 20 49 66 20 74 68 65 20 66  rs. .** If the f
1bc20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1bc30 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
1bc40 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
1bc50 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
1bc60 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1bc70 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
1bc80 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1bc90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
1bca0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1bcb0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
1bcc0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
1bcd0 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
1bce0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1bcf0 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
1bd00 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
1bd10 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
1bd20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
1bd30 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
1bd40 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
1bd50 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
1bd60 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
1bd70 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
1bd80 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
1bd90 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
1bda0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
1bdb0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
1bdc0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
1bdd0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
1bde0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
1bdf0 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68   freed..** If th
1be00 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1be10 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
1be20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1be30 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
1be40 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
1be50 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1be60 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
1be70 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
1be80 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1be90 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
1bea0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
1beb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1bec0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
1bed0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
1bee0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
1bef0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
1bf00 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c  zeros.  A zerobl
1bf10 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
1bf20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
1bf30 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
1bf40 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20  eger to hold it 
1bf50 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
1bf60 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
1bf70 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
1bf80 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
1bf90 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
1bfa0 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
1bfb0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
1bfc0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
1bfd0 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  n using .** [sql
1bfe0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
1bff0 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20   increment BLOB 
1c000 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20 41  I/O] routines. A
1c010 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c   negative.** val
1c020 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
1c030 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
1c040 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1c050 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  B..**.** The sql
1c060 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1c070 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
1c080 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b  alled after.** [
1c090 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c0a0 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76  v2()] (and its v
1c0b0 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c  ariants) or [sql
1c0c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e  ite3_reset()] an
1c0d0 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c  d.** before [sql
1c0e0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1c0f0 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f   Bindings are no
1c100 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
1c110 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1c120 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55  )] routine..** U
1c130 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
1c140 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
1c150 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
1c160 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1c170 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1c180 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
1c190 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
1c1a0 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f  f.** anything go
1c1b0 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49  es wrong.  [SQLI
1c1c0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
1c1d0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
1c1e0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
1c1f0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
1c200 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
1c210 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1c220 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
1c230 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
1c240 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  E] might be retu
1c250 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f  rned if these ro
1c260 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
1c270 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61  d on a.** virtua
1c280 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69  l machine that i
1c290 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74  s the wrong stat
1c2a0 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61  e or which has a
1c2b0 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61  lready been fina
1c2c0 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74  lized..** Detect
1c2d0 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73  ion of misuse is
1c2e0 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70   unreliable.  Ap
1c2f0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
1c300 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20  d not depend.** 
1c310 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  on SQLITE_MISUSE
1c320 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54   returns.  SQLIT
1c330 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65  E_MISUSE is inte
1c340 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  nded to indicate
1c350 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72   a.** a logic er
1c360 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69  ror in the appli
1c370 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20  cation.  Future 
1c380 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1c390 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69  te might.** pani
1c3a0 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65  c rather than re
1c3b0 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
1c3c0 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  SE..**.** See al
1c3d0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1c3e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1c3f0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
1c400 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1c410 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
1c420 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1c430 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1c440 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
1c450 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  NTS:.**.** {F135
1c460 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
1c470 5f 70 72 65 70 61 72 65 20 7c 20 53 51 4c 20 73  _prepare | SQL s
1c480 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
1c490 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 0a 2a 2a  r] recognizes.**
1c4a0 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 73            tokens
1c4b0 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 20 22 3f   of the forms "?
1c4c0 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56  ", "?NNN", "$VVV
1c4d0 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22  ", ":VVV", and "
1c4e0 40 56 56 56 22 0a 2a 2a 20 20 20 20 20 20 20 20  @VVV".**        
1c4f0 20 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74    as SQL paramet
1c500 65 72 73 2c 20 77 68 65 72 65 20 4e 4e 4e 20 69  ers, where NNN i
1c510 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f  s any sequence o
1c520 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  f one or more.**
1c530 20 20 20 20 20 20 20 20 20 20 64 69 67 69 74 73            digits
1c540 20 61 6e 64 20 77 68 65 72 65 20 56 56 56 20 69   and where VVV i
1c550 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f  s any sequence o
1c560 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a  f one or more .*
1c570 2a 20 20 20 20 20 20 20 20 20 20 61 6c 70 68 61  *          alpha
1c580 6e 75 6d 65 72 69 63 20 63 68 61 72 61 63 74 65  numeric characte
1c590 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f  rs or "::" optio
1c5a0 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62  nally followed b
1c5b0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  y.**          a 
1c5c0 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
1c5d0 67 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20  g no spaces and 
1c5e0 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
1c5f0 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a   parentheses..**
1c600 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20 54 68 65  .** {F13509} The
1c610 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f   initial value o
1c620 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
1c630 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  er is NULL..**.*
1c640 2a 20 7b 46 31 33 35 31 32 7d 20 54 68 65 20 69  * {F13512} The i
1c650 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53  ndex of an "?" S
1c660 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
1c670 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20  one larger than 
1c680 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1c690 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66  largest index of
1c6a0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
1c6b0 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31  o the left, or 1
1c6c0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
1c6d0 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c  the "?" is the l
1c6e0 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
1c6f0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
1c700 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20  3515} The index 
1c710 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c  of an "?NNN" SQL
1c720 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1c730 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a  e integer NNN..*
1c740 2a 0a 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54 68  *.** {F13518} Th
1c750 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a  e index of an ":
1c760 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72  VVV", "$VVV", or
1c770 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72 61   "@VVV" SQL para
1c780 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
1c790 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73       the same as
1c7a0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65   the index of le
1c7b0 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e 63  ftmost occurrenc
1c7c0 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  es of the same.*
1c7d0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
1c7e0 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72  eter, or one mor
1c7f0 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65  e than the large
1c800 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c  st index over al
1c810 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  l.**          pa
1c820 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
1c830 6c 65 66 74 20 69 66 20 74 68 69 73 20 69 73 20  left if this is 
1c840 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
1c850 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ence.**         
1c860 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   of this paramet
1c870 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73  er, or 1 if this
1c880 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
1c890 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1c8a0 2a 20 7b 46 31 33 35 32 31 7d 20 54 68 65 20 5b  * {F13521} The [
1c8b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1c8c0 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  | SQL statement 
1c8d0 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 20 77  compiler] fail w
1c8e0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
1c8f0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  an [SQLITE_RANGE
1c900 5d 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 69  ] error if the i
1c910 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
1c920 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
1c930 20 20 20 20 20 69 73 20 6c 65 73 73 20 74 68 61       is less tha
1c940 6e 20 31 20 6f 72 20 67 72 65 61 74 65 72 20 74  n 1 or greater t
1c950 68 61 6e 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56  han SQLITE_MAX_V
1c960 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a  ARIABLE_NUMBER..
1c970 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43  **.** {F13524} C
1c980 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1c990 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
1c9a0 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c  ite3_bind(S,N,V,
1c9b0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1c9c0 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 20    associate the 
1c9d0 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c  value V with all
1c9e0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
1c9f0 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20  having an.**    
1ca00 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e        index of N
1ca10 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
1ca20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
1ca30 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43  **.** {F13527} C
1ca40 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1ca50 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
1ca60 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e  ite3_bind(S,N,..
1ca70 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1ca80 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 63  override prior c
1ca90 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 61  alls with the sa
1caa0 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61  me values of S a
1cab0 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  nd N..**.** {F13
1cac0 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73  530} Bindings es
1cad0 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71  tablished by [sq
1cae0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
1caf0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
1cb00 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
1cb10 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f 73     persist acros
1cb20 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  s calls to [sqli
1cb30 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a  te3_reset(S)]..*
1cb40 2a 0a 2a 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e  *.** {F13533} In
1cb50 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1cb60 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
1cb70 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
1cb80 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
1cb90 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
1cba0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
1cbb0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
1cbc0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
1cbd0 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
1cbe0 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a  ds the first L.*
1cbf0 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65 73  *          bytes
1cc00 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 6f 72 20   of the blob or 
1cc10 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
1cc20 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a  o by V, when L.*
1cc30 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
1cc40 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
1cc50 2a 20 7b 46 31 33 35 33 36 7d 20 49 6e 20 63 61  * {F13536} In ca
1cc60 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1cc70 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
1cc80 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  L,D)] or.**     
1cc90 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
1cca0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
1ccb0 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
1ccc0 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a  ds characters.**
1ccd0 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56            from V
1cce0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
1ccf0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
1cd00 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61  r when L is nega
1cd10 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tive..**.** {F13
1cd20 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  539} In calls to
1cd30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1cd40 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
1cd50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1cd60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1cd70 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
1cd80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1cd90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1cda0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65  (S,N,V,L,D)] whe
1cdb0 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69  n D is the speci
1cdc0 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  al.**          c
1cdd0 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
1cde0 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20  STATIC], SQLite 
1cdf0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
1ce00 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20   value V.**     
1ce10 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20       is held in 
1ce20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64  static unmanaged
1ce30 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c   space that will
1ce40 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20   not change.**  
1ce50 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74          during t
1ce60 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74  he lifetime of t
1ce70 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a  he binding..**.*
1ce80 2a 20 7b 46 31 33 35 34 32 7d 20 49 6e 20 63 61  * {F13542} In ca
1ce90 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1cea0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
1ceb0 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
1cec0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
1ced0 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
1cee0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
1cef0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1cf00 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1cf10 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
1cf20 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
1cf30 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
1cf40 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
1cf50 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61  , the routine ma
1cf60 6b 65 73 20 61 20 0a 2a 2a 20 20 20 20 20 20 20  kes a .**       
1cf70 20 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20     private copy 
1cf80 6f 66 20 56 20 76 61 6c 75 65 20 62 65 66 6f 72  of V value befor
1cf90 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
1cfa0 0a 2a 2a 20 7b 46 31 33 35 34 35 7d 20 49 6e 20  .** {F13545} In 
1cfb0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1cfc0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
1cfd0 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
1cfe0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
1cff0 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
1d000 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
1d010 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
1d020 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
1d030 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61  ,D)] when D is a
1d040 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20   pointer to.**  
1d050 20 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69          a functi
1d060 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  on, SQLite invok
1d070 65 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  es that function
1d080 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a   to destroy the.
1d090 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20 76 61  **          V va
1d0a0 6c 75 65 20 61 66 74 65 72 20 69 74 20 68 61 73  lue after it has
1d0b0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
1d0c0 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a  the V value..**.
1d0d0 2a 2a 20 7b 46 31 33 35 34 38 7d 20 49 6e 20 63  ** {F13548} In c
1d0e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1d0f0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53  _bind_zeroblob(S
1d100 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c  ,N,V,L)] the val
1d110 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20  ue bound.**     
1d120 20 20 20 20 20 69 73 20 61 20 62 6c 6f 62 20 6f       is a blob o
1d130 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20  f L bytes, or a 
1d140 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62  zero-length blob
1d150 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76   if L is negativ
1d160 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 35 31  e..**.** {F13551
1d170 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1d180 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1d190 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20  e(S,N,V)] the V 
1d1a0 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20  argument may.** 
1d1b0 20 20 20 20 20 20 20 20 20 62 65 20 65 69 74 68           be eith
1d1c0 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20  er a [protected 
1d1d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
1d1e0 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20  bject or an.**  
1d1f0 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65          [unprote
1d200 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1d210 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69  ue] object..*/.i
1d220 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1d230 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
1d240 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
1d250 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
1d260 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
1d270 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
1d280 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
1d290 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
1d2a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1d2b0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
1d2c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
1d2d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1d2e0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
1d2f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
1d300 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
1d310 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
1d320 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
1d330 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
1d340 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
1d350 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d360 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
1d370 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
1d380 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
1d390 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
1d3a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1d3b0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
1d3c0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
1d3d0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1d3e0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
1d3f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1d400 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
1d410 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
1d420 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
1d430 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1d440 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
1d450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1d460 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
1d470 61 6d 65 74 65 72 73 20 7b 46 31 33 36 30 30 7d  ameters {F13600}
1d480 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1d490 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
1d4a0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
1d4b0 65 72 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65  er of SQL parame
1d4c0 74 65 72 73 0a 2a 2a 20 69 6e 20 61 20 70 72 65  ters.** in a pre
1d4d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
1d4e0 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
1d4f0 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
1d500 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
1d510 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
1d520 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
1d530 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
1d540 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
1d550 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
1d560 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
1d570 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
1d580 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
1d590 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
1d5a0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  time..**.** This
1d5b0 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
1d5c0 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
1d5d0 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
1d5e0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
1d5f0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
1d600 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
1d610 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
1d620 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
1d630 66 0a 2a 2a 20 75 6e 69 71 75 65 20 70 61 72 61  f.** unique para
1d640 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
1d650 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
1d660 4e 4e 20 61 72 65 20 75 73 65 64 2c 20 74 68 65  NN are used, the
1d670 72 65 20 6d 61 79 0a 2a 2a 20 62 65 20 67 61 70  re may.** be gap
1d680 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a  s in the list..*
1d690 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1d6a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1d6b0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1d6c0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1d6d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1d6e0 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
1d6f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1d700 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1d710 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1d720 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d  :.**.** {F13601}
1d730 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
1d740 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1d750 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  nt(S)] interface
1d760 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
1d770 20 20 20 20 20 74 68 65 20 6c 61 72 67 65 73 74       the largest
1d780 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51   index of all SQ
1d790 4c 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  L parameters in 
1d7a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1d7b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1d7c0 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20  ent] S, or 0 if 
1d7d0 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  S.**          co
1d7e0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61  ntains no SQL pa
1d7f0 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74  rameters..*/.int
1d800 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1d810 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
1d820 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
1d830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1d840 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
1d850 72 61 6d 65 74 65 72 20 7b 46 31 33 36 32 30 7d  rameter {F13620}
1d860 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1d870 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1d880 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d  inter to the nam
1d890 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a  e of the n-th.**
1d8a0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
1d8b0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
1d8c0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c  atement]..** SQL
1d8d0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
1d8e0 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
1d8f0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
1d900 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
1d910 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
1d920 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
1d930 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
1d940 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
1d950 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
1d960 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
1d970 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
1d980 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
1d990 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
1d9a0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
1d9b0 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
1d9c0 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20  ..** Parameters 
1d9d0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
1d9e0 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
1d9f0 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
1da00 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20   no name..**.** 
1da10 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
1da20 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1da30 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
1da40 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
1da50 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f  value n is out o
1da60 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
1da70 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
1da80 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
1da90 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
1daa0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74  turned.  The ret
1dab0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
1dac0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 74 68 65  ** always in the
1dad0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1dae0 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
1daf0 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
1db00 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
1db10 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
1db20 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
1db30 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
1db40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1db50 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1db60 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1db70 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1db80 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1db90 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1dba0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1dbb0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1dbc0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1dbd0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1dbe0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1dbf0 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20 54 68  *.** {F13621} Th
1dc00 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1dc10 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53  parameter_name(S
1dc20 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1dc30 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1dc40 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65     a UTF-8 rende
1dc50 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65  ring of the name
1dc60 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
1dc70 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20  meter in.**     
1dc80 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
1dc90 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69  tatement] S havi
1dca0 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a  ng index N, or.*
1dcb0 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  *          NULL 
1dcc0 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53  if there is no S
1dcd0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74  QL parameter wit
1dce0 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20  h index N or if 
1dcf0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1dd00 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
1dd10 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f  ndex N is an ano
1dd20 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
1dd30 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63   "?"..*/.const c
1dd40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
1dd50 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1dd60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1dd70 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
1dd80 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
1dd90 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
1dda0 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46   A Given Name {F
1ddb0 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74  13640}.**.** Ret
1ddc0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
1ddd0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
1dde0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
1ddf0 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20  .  The.** index 
1de00 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
1de10 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
1de20 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
1de30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1de40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1de50 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1de60 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20  ()].  A zero.** 
1de70 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
1de80 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
1de90 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
1dea0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
1deb0 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
1dec0 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
1ded0 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
1dee0 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
1def0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
1df00 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
1df10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1df20 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1df30 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1df40 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1df50 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1df60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1df70 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1df80 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
1df90 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1dfa0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1dfb0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1dfc0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20  .**.** {F13641} 
1dfd0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
1dfe0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1dff0 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  x(S,N)] interfac
1e000 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
1e010 20 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20        the index 
1e020 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
1e030 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74   in [prepared st
1e040 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20  atement].**     
1e050 20 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d       S whose nam
1e060 65 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54  e matches the UT
1e070 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72  F-8 string N, or
1e080 20 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a   0 if there is.*
1e090 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61  *          no ma
1e0a0 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  tch..*/.int sqli
1e0b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1e0c0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
1e0d0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
1e0e0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
1e0f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1e100 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
1e110 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
1e120 61 74 65 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d  atement {F13660}
1e130 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20  .**.** Contrary 
1e140 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
1e150 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
1e160 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
1e170 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68   not.** reset th
1e180 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1e190 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
1e1a0 20 6f 6e 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61   on a .** [prepa
1e1b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
1e1c0 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   Use this routin
1e1d0 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c  e to.** reset al
1e1e0 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
1e1f0 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  s to NULL..**.**
1e200 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1e210 2a 2a 20 7b 46 31 33 36 36 31 7d 20 54 68 65 20  ** {F13661} The 
1e220 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
1e230 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65  indings(S)] inte
1e240 72 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c  rface resets all
1e250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
1e260 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69   parameter bindi
1e270 6e 67 73 20 69 6e 20 5b 70 72 65 70 61 72 65 64  ngs in [prepared
1e280 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
1e290 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
1e2a0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
1e2b0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
1e2c0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
1e2d0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
1e2e0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
1e2f0 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
1e300 73 75 6c 74 20 53 65 74 20 7b 46 31 33 37 31 30  sult Set {F13710
1e310 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  }.**.** Return t
1e320 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1e330 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
1e340 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
1e350 62 79 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70  by the .** [prep
1e360 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1e370 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
1e380 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53  turns 0.** if pS
1e390 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74  tmt is an SQL st
1e3a0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
1e3b0 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
1e3c0 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70  a (for .** examp
1e3d0 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a  le an UPDATE)..*
1e3e0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1e3f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20  .**.** {F13711} 
1e400 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
1e410 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e  umn_count(S)] in
1e420 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1e430 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1e440 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e            column
1e450 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
1e460 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 79  set generated by
1e470 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e480 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1e490 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66  ment] S, or 0 if
1e4a0 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65   S does not gene
1e4b0 72 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rate.**         
1e4c0 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a   a result set..*
1e4d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
1e4e0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
1e4f0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1e500 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e510 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
1e520 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
1e530 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13720}.**.** Th
1e540 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1e550 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
1e560 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
1e570 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
1e580 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
1e590 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
1e5a0 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
1e5b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1e5c0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
1e5d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1e5e0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
1e5f0 6d 69 6e 61 74 65 64 20 55 54 46 38 20 73 74 72  minated UTF8 str
1e600 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
1e610 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
1e620 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
1e630 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
1e640 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1e650 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
1e660 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1e670 69 73 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  is the.** [prepa
1e680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1e690 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
1e6a0 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  he SELECT statem
1e6b0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ent..** The seco
1e6c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1e6d0 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  the column numbe
1e6e0 72 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73  r.  The left-mos
1e6f0 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e  t column is.** n
1e700 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54  umber 0..**.** T
1e710 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1e720 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
1e730 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
1e740 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72   the .** [prepar
1e750 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
1e760 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
1e770 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1e780 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  )].** or until t
1e790 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c  he next call sql
1e7a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1e7b0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
1e7c0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a  lumn_name16().**
1e7d0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
1e7e0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71  umn..**.** If sq
1e7f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
1e800 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
1e810 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
1e820 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
1e830 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
1e840 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
1e850 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
1e860 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
1e870 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
1e880 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1e890 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72   The name of a r
1e8a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
1e8b0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
1e8c0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
1e8d0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
1e8e0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
1e8f0 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
1e900 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
1e910 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
1e920 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
1e930 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
1e940 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
1e950 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
1e960 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
1e970 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a  to the next..**.
1e980 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1e990 2a 0a 2a 2a 20 7b 46 31 33 37 32 31 7d 20 41 20  *.** {F13721} A 
1e9a0 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
1e9b0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  ation of the [sq
1e9c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1e9d0 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  e(S,N)].**      
1e9e0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65      interface re
1e9f0 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a  turns the name.*
1ea00 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
1ea10 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
1ea20 65 72 65 20 30 20 69 73 20 74 68 65 20 6c 65 66  ere 0 is the lef
1ea30 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66  t-most column) f
1ea40 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
1ea50 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
1ea60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ea70 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20  ment] S as a.** 
1ea80 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1ea90 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1eaa0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
1eab0 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73 66  3723} A successf
1eac0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
1ead0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
1eae0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
1eaf0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
1eb00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1eb10 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
1eb20 20 20 20 20 20 6f 66 20 74 68 65 20 4e 74 68 20       of the Nth 
1eb30 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20  column (where 0 
1eb40 69 73 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74  is the left-most
1eb50 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65   column) for the
1eb60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
1eb70 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
1eb80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1eb90 53 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  S as a.**       
1eba0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
1ebb0 65 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ed UTF-16 string
1ebc0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1ebd0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
1ebe0 20 7b 46 31 33 37 32 34 7d 20 54 68 65 20 5b 73   {F13724} The [s
1ebf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1ec00 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  me()] and [sqlit
1ec10 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
1ec20 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1ec30 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
1ec40 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
1ec50 20 69 66 20 74 68 65 79 20 61 72 65 20 75 6e 61   if they are una
1ec60 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ble to.**       
1ec70 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f     allocate memo
1ec80 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 69 72  ry to hold their
1ec90 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20 73   normal return s
1eca0 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  trings..**.** {F
1ecb0 31 33 37 32 35 7d 20 49 66 20 74 68 65 20 4e 20  13725} If the N 
1ecc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1ecd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1ece0 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20  e(S,N)] or.**   
1ecf0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1ed00 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
1ed10 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 20 72 61  N)] is out of ra
1ed20 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  nge, then the.**
1ed30 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
1ed40 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55  aces return a NU
1ed50 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a  LL pointer..** .
1ed60 2a 2a 20 7b 46 31 33 37 32 36 7d 20 54 68 65 20  ** {F13726} The 
1ed70 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1ed80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
1ed90 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61  umn_name(S,N)] a
1eda0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1edb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1edc0 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 65 20  ame16(S,N)] are 
1edd0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
1ede0 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  next.**         
1edf0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
1ee00 72 6f 75 74 69 6e 65 20 77 69 74 68 20 74 68 65  routine with the
1ee10 20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 70 61   same S and N pa
1ee20 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20  rameters.**     
1ee30 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73       or until [s
1ee40 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1ee50 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a  S)] is called..*
1ee60 2a 0a 2a 2a 20 7b 46 31 33 37 32 37 7d 20 57 68  *.** {F13727} Wh
1ee70 65 6e 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  en a result colu
1ee80 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  mn of a [SELECT]
1ee90 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61   statement conta
1eea0 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ins.**          
1eeb0 61 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 74 68  an AS clause, th
1eec0 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 63  e name of that c
1eed0 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 64 65  olumn is the ide
1eee0 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20 20  ntifier.**      
1eef0 20 20 20 20 74 6f 20 74 68 65 20 72 69 67 68 74      to the right
1ef00 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f   of the AS keywo
1ef10 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  rd..*/.const cha
1ef20 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
1ef30 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
1ef40 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
1ef50 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1ef60 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1ef70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1ef80 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
1ef90 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
1efa0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
1efb0 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37 34 30  y Result {F13740
1efc0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
1efd0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
1efe0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
1eff0 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20  ine what column 
1f000 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65  of what.** table
1f010 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61   in which databa
1f020 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  se a result of a
1f030 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1f040 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a  t comes from..**
1f050 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
1f060 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
1f070 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
1f080 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
1f090 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 38  ** either a UTF8
1f0a0 20 6f 72 20 55 54 46 31 36 20 73 74 72 69 6e 67   or UTF16 string
1f0b0 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65  .  The _database
1f0c0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
1f0d0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
1f0e0 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
1f0f0 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
1f100 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
1f110 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
1f120 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
1f130 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
1f140 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72  n name..** The r
1f150 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1f160 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a  s valid until.**
1f170 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1f180 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
1f190 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20  troyed using.** 
1f1a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1f1b0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
1f1c0 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1f1d0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
1f1e0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
1f1f0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
1f200 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
1f210 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
1f220 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
1f230 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
1f240 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
1f250 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
1f260 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  mn..**.** The fi
1f270 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1f280 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
1f290 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  lls is a [prepar
1f2a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1f2b0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
1f2c0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
1f2d0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
1f2e0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
1f2f0 65 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73 74  ed by .** the st
1f300 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
1f310 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
1f320 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
1f330 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e  ..**.** If the N
1f340 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
1f350 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
1f360 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
1f370 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75  sion.** or subqu
1f380 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
1f390 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
1f3a0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
1f3b0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
1f3c0 74 75 72 6e 20 4e 55 4c 4c 2e 20 20 54 68 65 73  turn NULL.  Thes
1f3d0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
1f3e0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
1f3f0 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20   if a memory.** 
1f400 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1f410 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77   occurs.  Otherw
1f420 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
1f430 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66   the .** name of
1f440 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
1f450 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e  tabase, table an
1f460 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  d column that qu
1f470 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ery result.** co
1f480 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
1f490 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41  ed from..**.** A
1f4a0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
1f4b0 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
1f4c0 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69  ose postfixed wi
1f4d0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
1f4e0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
1f4f0 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74   strings, the ot
1f500 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
1f510 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44  turn UTF-8. {END
1f520 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50  }.**.** These AP
1f530 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
1f540 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
1f550 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
1f560 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
1f570 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
1f580 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65  UMN_METADATA pre
1f590 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
1f5a0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
1f5b0 7b 55 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74  {U13751}.** If t
1f5c0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
1f5d0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
1f5e0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
1f5f0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
1f600 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
1f610 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
1f620 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
1f630 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
1f640 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
1f650 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
1f660 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1f670 0a 2a 2a 20 7b 46 31 33 37 34 31 7d 20 54 68 65  .** {F13741} The
1f680 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1f690 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53  _database_name(S
1f6a0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1f6b0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
1f6c0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
1f6d0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1f6e0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
1f6f0 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68  database from wh
1f700 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
1f710 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
1f720 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
1f730 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1f740 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
1f750 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
1f760 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
1f770 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
1f780 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
1f790 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
1f7a0 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
1f7b0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
1f7c0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
1f7d0 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
1f7e0 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
1f7f0 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c 69  13742} The [sqli
1f800 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
1f810 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  ase_name16(S,N)]
1f820 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1f830 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
1f840 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
1f850 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1f860 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  er.**          z
1f870 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
1f880 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1f890 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ase from which t
1f8a0 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
1f8b0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
1f8c0 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  n of [prepared s
1f8d0 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20  tatement] S .** 
1f8e0 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74 72           is extr
1f8f0 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
1f900 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
1f910 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1f920 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1f930 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1f940 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1f950 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1f960 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1f970 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1f980 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 33       .** {F13743
1f990 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1f9a0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
1f9b0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
1f9c0 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
1f9d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1f9e0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1f9f0 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
1fa00 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69  e table from whi
1fa10 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
1fa20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
1fa30 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
1fa40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1fa50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1fa60 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
1fa70 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
1fa80 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a  lumn of S is a.*
1fa90 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72  *          gener
1faa0 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  al expression or
1fab0 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
1fac0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a  locate memory.**
1fad0 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f            to sto
1fae0 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  re the name..** 
1faf0 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31           .** {F1
1fb00 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3744} The [sqlit
1fb10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
1fb20 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
1fb30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
1fb40 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
1fb50 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
1fb60 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
1fb70 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
1fb80 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
1fb90 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f  of the table fro
1fba0 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20  m which the .** 
1fbb0 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
1fbc0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70  ult column of [p
1fbd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fbe0 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20  t] S .**        
1fbf0 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20    is extracted, 
1fc00 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
1fc10 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
1fc20 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
1fc30 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
1fc40 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20  on or if unable 
1fc50 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1fc60 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ry.**          t
1fc70 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
1fc80 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a  ..**          .*
1fc90 2a 20 7b 46 31 33 37 34 35 7d 20 54 68 65 20 5b  * {F13745} The [
1fca0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
1fcb0 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  rigin_name(S,N)]
1fcc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1fcd0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
1fce0 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
1fcf0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1fd00 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
1fd10 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68  e column from wh
1fd20 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
1fd30 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
1fd40 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
1fd50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1fd60 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
1fd70 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
1fd80 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
1fd90 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
1fda0 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
1fdb0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
1fdc0 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
1fdd0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
1fde0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
1fdf0 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
1fe00 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
1fe10 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69  13746} The [sqli
1fe20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
1fe30 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
1fe40 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1fe50 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
1fe60 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
1fe70 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1fe80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1fe90 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
1fea0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1feb0 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
1fec0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1fed0 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
1fee0 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
1fef0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
1ff00 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
1ff10 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
1ff20 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
1ff30 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20  mn of S is a.** 
1ff40 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c           general
1ff50 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69   expression or i
1ff60 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
1ff70 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  cate memory.**  
1ff80 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65          to store
1ff90 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20   the name..**   
1ffa0 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37         .** {F137
1ffb0 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  48} The return v
1ffc0 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20  alues from.**   
1ffd0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1ffe0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1fff0 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61  name|column meta
20000 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
20010 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
20020 20 76 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20 20   valid.**       
20030 20 20 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74     for the lifet
20040 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70  ime of the [prep
20050 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
20060 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75  **          or u
20070 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e  ntil the encodin
20080 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79 20  g is changed by 
20090 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61  another metadata
200a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
200b0 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20  erface call for 
200c0 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72 65  the same prepare
200d0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
200e0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49  column..**.** LI
200f0 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
20100 20 7b 55 31 33 37 35 31 7d 20 49 66 20 74 77 6f   {U13751} If two
20110 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
20120 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
20130 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
20140 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
20150 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75  tabase_name|colu
20160 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
20170 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20  rfaces].**      
20180 20 20 20 20 74 68 65 20 73 61 6d 65 20 5b 70 72      the same [pr
20190 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
201a0 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
201b0 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  umn.**          
201c0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
201d0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
201e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
201f0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
20200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
20210 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
20220 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
20230 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
20240 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
20250 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
20260 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
20270 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
20280 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
20290 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
202a0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
202b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
202c0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
202d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
202e0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
202f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
20300 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
20310 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
20320 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
20330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
20340 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
20350 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
20360 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
20370 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
20380 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
20390 6c 74 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a  lt {F13760}.**.*
203a0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
203b0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
203c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
203d0 20 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61   .** If this sta
203e0 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45  tement is a SELE
203f0 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  CT statement and
20400 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
20410 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72  of the .** retur
20420 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
20430 66 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73  f that SELECT is
20440 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
20450 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
20460 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
20470 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
20480 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
20490 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
204a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49   is returned.  I
204b0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
204c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
204d0 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
204e0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
204f0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
20500 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
20510 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75  ned..** The retu
20520 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
20530 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
20540 64 65 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20  ded.  {END} .** 
20550 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  For example, in 
20560 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
20570 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
20580 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
20590 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e  RIANT);.**.** An
205a0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
205b0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
205c0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
205d0 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
205e0 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20   t1;.**.** Then 
205f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
20600 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
20610 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
20620 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  or the second.**
20630 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
20640 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
20650 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
20660 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
20670 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e  olumn.** (i==0).
20680 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
20690 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
206a0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20  ime typing.  So 
206b0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
206c0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
206d0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
206e0 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
206f0 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
20700 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
20710 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
20720 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
20730 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
20740 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
20750 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
20760 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
20770 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
20780 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20  ic.  Type.** is 
20790 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
207a0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
207b0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
207c0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
207d0 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
207e0 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49   values..**.** I
207f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
20800 20 7b 46 31 33 37 36 31 7d 20 20 41 20 73 75 63   {F13761}  A suc
20810 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
20820 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
20830 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a 2a  decltype(S,N)].*
20840 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
20850 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  rns a zero-termi
20860 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
20870 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
20880 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
20890 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61  he declared data
208a0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
208b0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
208c0 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  pears.**        
208d0 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f     as the Nth co
208e0 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66  lumn (numbered f
208f0 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
20900 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a  sult set to the.
20910 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
20920 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20930 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ] S..**.** {F137
20940 36 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75  62}  A successfu
20950 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
20960 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
20970 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  pe16(S,N)].**   
20980 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
20990 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
209a0 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
209b0 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e  byte order strin
209c0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  g.**           c
209d0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65  ontaining the de
209e0 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20  clared datatype 
209f0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
20a00 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73  umn that appears
20a10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73  .**           as
20a20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
20a30 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30  (numbered from 0
20a40 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  ) of the result 
20a50 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  set to the.**   
20a60 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
20a70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
20a80 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20  **.** {F13763}  
20a90 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
20aa0 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61  n 0 or N is grea
20ab0 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ter than or equa
20ac0 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  l to.**         
20ad0 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20    the number of 
20ae0 63 6f 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65 70  columns in [prep
20af0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20b00 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  S.**           o
20b10 72 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  r if the Nth col
20b20 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65  umn of S is an e
20b30 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
20b40 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20  query rather.** 
20b50 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 61            than a
20b60 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72   table column or
20b70 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
20b80 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a  ocation failure.
20b90 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63  **           occ
20ba0 75 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64  urs during encod
20bb0 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c  ing conversions,
20bc0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
20bd0 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c     calls to [sql
20be0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
20bf0 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  type(S,N)] or.**
20c00 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
20c10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
20c20 79 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75  ype16(S,N)] retu
20c30 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73  rn NULL..*/.cons
20c40 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
20c50 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
20c60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
20c70 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
20c80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
20c90 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
20ca0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
20cb0 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  * .** CAPI3REF: 
20cc0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
20cd0 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 32   Statement {F132
20ce0 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  00}.**.** After 
20cf0 61 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  an [prepared sta
20d00 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
20d10 20 70 72 65 70 61 72 65 64 20 77 69 74 68 20 61   prepared with a
20d20 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68   call.** to eith
20d30 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
20d40 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
20d50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
20d60 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20  v2()] or to one 
20d70 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79  of.** the legacy
20d80 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
20d90 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
20da0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
20db0 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65  are16()],.** the
20dc0 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  n this function 
20dd0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
20de0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
20df0 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
20e00 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a   .** statement..
20e10 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
20e20 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
20e30 72 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65  r of this sqlite
20e40 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
20e50 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
20e60 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
20e70 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
20e80 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
20e90 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
20ea0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
20eb0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
20ec0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20ed0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
20ee0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
20ef0 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
20f00 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
20f10 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
20f20 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
20f30 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
20f40 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
20f50 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
20f60 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
20f70 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
20f80 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
20f90 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
20fa0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
20fb0 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63  .** In the legac
20fc0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
20fd0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
20fe0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
20ff0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20  LITE_BUSY], .** 
21000 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
21010 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
21020 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
21030 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
21040 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32  .** With the "v2
21050 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
21060 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53   of the other [S
21070 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
21080 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53  t code].** or [S
21090 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
210a0 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
210b0 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62  lt code] might b
210c0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
210d0 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51   well..**.** [SQ
210e0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
210f0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
21100 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
21110 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
21120 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
21130 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
21140 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49  o do its job.  I
21150 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
21160 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f  is a COMMIT.** o
21170 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
21180 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
21190 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
211a0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
211b0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
211c0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
211d0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d  ent is not a COM
211e0 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77  MIT and occurs w
211f0 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
21200 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
21210 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
21220 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
21230 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
21240 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
21250 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
21260 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
21270 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
21280 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
21290 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
212a0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
212b0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
212c0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
212d0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
212e0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
212f0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
21300 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
21310 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
21320 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
21330 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
21340 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
21350 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
21360 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
21370 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
21380 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a  ny data, then .*
21390 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69  * [SQLITE_ROW] i
213a0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
213b0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
213c0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 0a  f data is ready.
213d0 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  ** for processin
213e0 67 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e  g by the caller.
213f0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
21400 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
21410 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
21420 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63  3_column_int | c
21430 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
21440 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
21450 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
21460 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
21470 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
21480 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20  row of data..** 
21490 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
214a0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
214b0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
214c0 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
214d0 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
214e0 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
214f0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
21500 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
21510 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
21520 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
21530 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
21540 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
21550 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
21560 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  sg()]..** With t
21570 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
21580 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
21590 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
215a0 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51  (example:.** [SQ
215b0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
215c0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
215d0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
215e0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
215f0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
21600 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
21610 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
21620 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
21630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21640 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  .  In the "v2" i
21650 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
21660 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
21670 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
21680 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
21690 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
216a0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
216b0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
216c0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
216d0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
216e0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
216f0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
21700 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
21710 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21720 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
21730 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
21740 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
21750 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
21760 20 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a   one that had .*
21770 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
21780 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
21790 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
217a0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
217b0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
217c0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
217d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
217e0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
217f0 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
21800 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
21810 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
21820 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c  in time..**.** <
21830 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
21840 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20  e Alert:</b>.** 
21850 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
21860 74 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65  terface, .** the
21870 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
21880 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
21890 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
218a0 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c  or code,.** [SQL
218b0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
218c0 6f 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20  owing any error 
218d0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
218e0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20  TE_BUSY].** and 
218f0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
21900 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20    You must call 
21910 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
21920 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
21930 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
21940 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
21950 65 20 6f 66 20 74 68 65 20 73 70 65 63 69 66 69  e of the specifi
21960 63 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  c.** [error code
21970 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
21980 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
21990 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
219a0 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
219b0 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
219c0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
219d0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
219e0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
219f0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
21a00 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
21a10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
21a20 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
21a30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21a40 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
21a50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
21a60 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
21a70 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
21a80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
21a90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
21aa0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20  pare16()], then 
21ab0 74 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65  the .** more spe
21ac0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
21ad0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
21ae0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
21af0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
21b00 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
21b10 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
21b20 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
21b30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
21b40 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20  .**.** {F13202} 
21b50 20 49 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   If [prepared st
21b60 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65  atement] S is re
21b70 61 64 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20 20  ady to be.**    
21b80 20 20 20 20 20 20 20 72 75 6e 2c 20 74 68 65 6e         run, then
21b90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
21ba0 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74  )] advances that
21bb0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
21bc0 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
21bd0 20 75 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c 65   until to comple
21be0 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74  tion or until it
21bf0 20 69 73 20 72 65 61 64 79 20 74 6f 20 72 65 74   is ready to ret
21c00 75 72 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20 20  urn another.**  
21c10 20 20 20 20 20 20 20 20 20 72 6f 77 20 6f 66 20           row of 
21c20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
21c30 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 6f  r an interrupt o
21c40 72 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  r run-time error
21c50 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b   occurs..**.** {
21c60 46 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20  F15304}  When a 
21c70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
21c80 5f 73 74 65 70 28 53 29 5d 20 63 61 75 73 65 73  _step(S)] causes
21c90 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
21ca0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
21cb0 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75 6e  tement] S to run
21cc0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a   to completion,.
21cd0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
21ce0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
21cf0 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  s [SQLITE_DONE].
21d00 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20  .**.** {F15306} 
21d10 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20   When a call to 
21d20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
21d30 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73 65 20  ] stops because 
21d40 69 74 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 20  it is ready.**  
21d50 20 20 20 20 20 20 20 20 20 74 6f 20 72 65 74 75           to retu
21d60 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f  rn another row o
21d70 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
21d80 2c 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  , it returns.** 
21d90 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
21da0 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  E_ROW]..**.** {F
21db0 31 35 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c  15308}  If a cal
21dc0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
21dd0 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72  ep(S)] encounter
21de0 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  s an.**         
21df0 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72    [sqlite3_inter
21e00 72 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20  rupt|interrupt] 
21e10 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  or a run-time er
21e20 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
21e30 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20    it returns an 
21e40 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
21e50 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e  r code that is n
21e60 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20  ot one of.**    
21e70 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
21e80 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  K], [SQLITE_ROW]
21e90 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  , or [SQLITE_DON
21ea0 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31  E]..**.** {F1531
21eb0 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74  0}  If an [sqlit
21ec0 65 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74  e3_interrupt|int
21ed0 65 72 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d 74  errupt] or run-t
21ee0 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20  ime error.**    
21ef0 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
21f00 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  ring a call to [
21f10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
21f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f  .**           fo
21f30 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
21f40 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74  atement] S creat
21f50 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
21f60 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74        legacy int
21f70 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
21f80 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
21f90 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
21fa0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
21fb0 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  ] then the funct
21fc0 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68  ion returns eith
21fd0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
21fe0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
21ff0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f  [SQLITE_BUSY], o
22000 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
22010 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
22020 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
22030 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
22040 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
22050 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
22060 65 73 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37  esult set {F1377
22070 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0}.**.** Return 
22080 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  the number of va
22090 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72  lues in the curr
220a0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
220b0 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  esult set..**.**
220c0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
220d0 2a 2a 20 7b 46 31 33 37 37 31 7d 20 20 41 66 74  ** {F13771}  Aft
220e0 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  er a call to [sq
220f0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74  lite3_step(S)] t
22100 68 61 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  hat returns.**  
22110 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
22120 5f 52 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c 69  _ROW], the [sqli
22130 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53  te3_data_count(S
22140 29 5d 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20  )] routine.**   
22150 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74          will ret
22160 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c  urn the same val
22170 75 65 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20  ue as the.**    
22180 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
22190 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d  column_count(S)]
221a0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
221b0 20 7b 46 31 33 37 37 32 7d 20 20 41 66 74 65 72   {F13772}  After
221c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
221d0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
221e0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
221f0 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
22200 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f    [SQLITE_ROW] o
22210 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  r before [sqlite
22220 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62  3_step(S)] has b
22230 65 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  een .**         
22240 20 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20    called on the 
22250 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22260 65 6e 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20  ent] for.**     
22270 20 20 20 20 20 20 74 68 65 20 66 69 72 73 74 20        the first 
22280 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61  time since it wa
22290 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
222a0 72 65 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a 20  re|prepared].** 
222b0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
222c0 6c 69 74 65 33 5f 72 65 73 65 74 7c 72 65 73 65  lite3_reset|rese
222d0 74 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  t], the [sqlite3
222e0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 0a  _data_count(S)].
222f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f 75  **           rou
22300 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
22310 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
22320 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
22330 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
22340 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22350 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
22360 44 61 74 61 74 79 70 65 73 20 7b 46 31 30 32 36  Datatypes {F1026
22370 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  5}.** KEYWORDS: 
22380 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
22390 2a 20 7b 46 31 30 32 36 36 7d 45 76 65 72 79 20  * {F10266}Every 
223a0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
223b0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
223c0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
223d0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
223e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
223f0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
22400 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
22410 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
22420 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
22430 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
22440 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
22450 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  LL.** </ul> {END
22460 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
22470 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
22480 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
22490 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
224a0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
224b0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
224c0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
224d0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
224e0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
224f0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
22500 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
22510 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
22520 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
22530 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
22540 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
22550 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
22560 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  se SQLITE3_TEXT 
22570 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
22580 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
22590 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
225a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
225b0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
225c0 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
225d0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
225e0 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
225f0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
22600 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
22610 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
22620 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
22630 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
22640 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
22650 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
22660 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
22670 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  s Values From A 
22680 51 75 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a  Query {F13800}.*
22690 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
226a0 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
226b0 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20  sult set query" 
226c0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
226d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
226e0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
226f0 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69  on about.** a si
22700 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
22710 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c  he current resul
22720 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
22730 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63  .  In every.** c
22740 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
22750 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
22760 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b  ter to the .** [
22770 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22780 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
22790 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28  g.** evaluated (
227a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
227b0 74 2a 5d 20 74 68 61 74 20 77 61 73 20 72 65 74  t*] that was ret
227c0 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  urned from .** [
227d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
227e0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
227f0 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e  its variants) an
22800 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  d.** the second 
22810 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
22820 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
22830 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
22840 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68  formation .** sh
22850 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
22860 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  .  The left-most
22870 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
22880 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73  esult set.** has
22890 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a   an index of 0..
228a0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
228b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
228c0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
228d0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
228e0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74  , or if the.** t
228f0 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  he column index 
22900 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
22910 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
22920 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68  ndefined. .** Th
22930 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
22940 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
22950 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
22960 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
22970 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22980 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
22990 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
229a0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
229b0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
229c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
229d0 65 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  e()] has been ca
229e0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ll subsequently.
229f0 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
22a00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
22a10 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
22a20 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22a30 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
22a40 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
22a50 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
22a60 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
22a70 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
22a80 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
22a90 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
22aa0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
22ab0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
22ac0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
22ad0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
22ae0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
22af0 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
22b00 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
22b10 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
22b20 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
22b30 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
22b40 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
22b50 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
22b60 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a  defined.  .**.**
22b70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
22b80 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
22b90 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  ne returns .** [
22ba0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
22bb0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
22bc0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
22bd0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
22be0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
22bf0 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  n.  The returned
22c00 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
22c10 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
22c20 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
22c30 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
22c40 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
22c50 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
22c60 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
22c70 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
22c80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22c90 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
22ca0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
22cb0 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
22cc0 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
22cd0 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
22ce0 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
22cf0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
22d00 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
22d10 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
22d20 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
22d30 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
22d40 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
22d50 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
22d60 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
22d70 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
22d80 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
22d90 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
22da0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
22db0 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
22dc0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
22dd0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
22de0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
22df0 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75  _bytes() .** rou
22e00 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
22e10 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
22e20 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
22e30 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74   string..** If t
22e40 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
22e50 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
22e60 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
22e70 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
22e80 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
22e90 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
22ea0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
22eb0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
22ec0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
22ed0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
22ee0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
22ef0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
22f00 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
22f10 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
22f20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
22f30 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
22f40 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
22f50 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
22f60 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
22f70 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76  string..** The v
22f80 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f  alue returned do
22f90 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
22fa0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
22fb0 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  or at the end.**
22fc0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
22fd0 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68   For clarity: th
22fe0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
22ff0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
23000 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
23010 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
23020 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
23030 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74  acters..**.** St
23040 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
23050 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
23060 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
23070 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
23080 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
23090 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
230a0 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d  always zero term
230b0 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 74  inated.  The ret
230c0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
230d0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
230e0 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
230f0 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69  ro-length blob i
23100 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a  s an arbitrary.*
23110 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69  * pointer, possi
23120 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20  bly even a NULL 
23130 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
23140 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
23150 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74  n_bytes16() rout
23160 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
23170 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
23180 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20  _bytes().** but 
23190 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c  leaves the resul
231a0 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e  t in UTF-16 in n
231b0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
231c0 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d   instead of UTF-
231d0 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f  8.  .** The zero
231e0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e   terminator is n
231f0 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ot included in t
23200 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a  his count..**.**
23210 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75   The object retu
23220 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
23230 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
23240 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
23250 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
23260 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
23270 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
23280 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
23290 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
232a0 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
232b0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
232c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
232d0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
232e0 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
232f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23300 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
23310 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
23320 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
23330 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
23340 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
23350 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
23360 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
23370 69 6b 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ike .** [sqlite3
23380 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
23390 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
233a0 78 74 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  xt()], or [sqlit
233b0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
233c0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  ],.** then the b
233d0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
233e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
233f0 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
23400 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
23410 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
23420 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a  propriate.  For.
23430 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
23440 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
23450 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
23460 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
23470 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
23480 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
23490 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
234a0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
234b0 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73  o do the convers
234c0 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ion.** automatic
234d0 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f  ally.  The follo
234e0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
234f0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
23500 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61  ns that.** are a
23510 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
23520 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
23530 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
23540 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
23550 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
23560 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
23570 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
23580 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
23590 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
235a0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
235b0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
235c0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
235d0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
235e0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
235f0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
23600 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
23610 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
23620 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
23630 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
23640 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
23650 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
23660 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
23670 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
23680 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
23690 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
236a0 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
236b0 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
236c0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
236d0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
236e0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
236f0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
23700 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
23710 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
23720 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
23730 65 20 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52  e as for INTEGER
23740 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
23750 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
23760 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
23770 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
23780 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
23790 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
237a0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
237b0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
237c0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
237d0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
237e0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
237f0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
23800 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
23810 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
23820 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
23830 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
23840 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
23850 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
23860 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
23870 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
23880 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
23890 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
238a0 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
238b0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
238c0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
238d0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
238e0 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
238f0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
23900 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
23910 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
23920 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
23930 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
23940 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
23950 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
23960 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
23970 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
23980 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
23990 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
239a0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  te>.**.** The ta
239b0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
239c0 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
239d0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
239e0 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
239f0 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
23a00 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
23a10 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
23a20 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
23a30 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
23a40 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
23a50 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
23a60 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
23a70 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
23a80 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
23a90 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
23aa0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
23ab0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
23ac0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
23ad0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
23ae0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
23af0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
23b00 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
23b10 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
23b20 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
23b30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
23b40 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
23b50 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
23b60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
23b70 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
23b80 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20  be invalidated. 
23b90 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
23ba0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
23bb0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
23bc0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
23bd0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
23be0 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
23bf0 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
23c00 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
23c10 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
23c20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23c30 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  xt() .**        
23c40 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c    or sqlite3_col
23c50 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
23c60 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
23c70 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
23c80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 65  .**          nee
23c90 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
23ca0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e   the string.</p>
23cb0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
23cc0 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c  <p>  The initial
23cd0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
23ce0 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
23cf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
23d00 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  6() or.**       
23d10 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
23d20 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
23d30 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
23d40 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
23d50 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rted.**         
23d60 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c   to UTF-16.</p><
23d70 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c  /li>.**.** <li><
23d80 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20  p>  The initial 
23d90 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
23da0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
23db0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23dc0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ) or.**         
23dd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23de0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
23df0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
23e00 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
23e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
23e20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a  UTF-8.</p></li>.
23e30 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43  ** </ul>.**.** C
23e40 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
23e50 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
23e60 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
23e70 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
23e80 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
23e90 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
23ea0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
23eb0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
23ec0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
23ed0 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
23ee0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
23ef0 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20   points to will 
23f00 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
23f10 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
23f20 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
23f30 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
23f40 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
23f50 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
23f60 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e  etime it is.** n
23f70 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
23f80 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
23f90 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
23fa0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 20  e invalidated.  
23fb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
23fc0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
23fd0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
23fe0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
23ff0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
24000 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
24010 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
24020 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  .**  <ul>.**  <l
24030 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
24040 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
24050 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
24060 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
24070 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
24080 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
24090 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
240a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
240b0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
240c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
240d0 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
240e0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
240f0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
24100 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  **  </ul>.**.** 
24110 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
24120 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
24130 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24140 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  ext(), sqlite3_c
24150 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  olumn_blob(),.**
24160 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
24170 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
24180 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
24190 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65 20 64  esult into the d
241a0 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74  esired.** format
241b0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
241c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
241d0 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  es() or sqlite3_
241e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
241f0 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20   to.** find the 
24200 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
24210 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
24220 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
24230 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
24240 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
24250 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
24260 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
24270 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
24280 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a  .  And do not.**
24290 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
242a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
242b0 74 31 36 28 29 20 77 69 74 68 20 63 61 6c 6c 73  t16() with calls
242c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
242d0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
242e0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72  * The pointers r
242f0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
24300 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
24310 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
24320 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
24330 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
24340 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24350 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
24360 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
24370 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
24380 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ] is called.  Th
24390 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
243a0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
243b0 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73  ngs.** and blobs
243c0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
243d0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
243e0 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
243f0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
24400 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
24410 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
24420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24430 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
24440 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  o .** [sqlite3_f
24450 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ree()]..**.** If
24460 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
24470 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
24480 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
24490 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
244a0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
244b0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
244c0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
244d0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
244e0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
244f0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
24500 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
24510 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
24520 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
24530 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
24540 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
24550 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
24560 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
24570 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
24580 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
24590 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54  **.** {F13803} T
245a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
245b0 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e  mn_blob(S,N)] in
245c0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
245d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
245e0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
245f0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
24600 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
24610 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
24620 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24630 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 62  ment] S into a b
24640 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74  lob and then ret
24650 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
24660 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68     pointer to th
24670 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
24680 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36  e..**.** {F13806
24690 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
246a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29  olumn_bytes(S,N)
246b0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
246c0 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
246d0 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
246e0 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f 62 20  tes in the blob 
246f0 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  or string (exclu
24700 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
24710 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
24720 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
24730 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
24740 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
24750 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
24760 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
24770 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24780 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  blob(S,N)] or.**
24790 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
247a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
247b0 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ,N)]..**.** {F13
247c0 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  809} The [sqlite
247d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
247e0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
247f0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
24800 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
24810 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
24820 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
24830 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
24840 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
24850 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
24860 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
24870 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
24880 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
24890 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
248a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
248b0 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  t16(S,N)]..**.**
248c0 20 7b 46 31 33 38 31 32 7d 20 54 68 65 20 5b 73   {F13812} The [s
248d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
248e0 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  uble(S,N)] inter
248f0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
24900 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
24910 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
24920 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
24930 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
24940 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
24950 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24960 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61  t] S into a floa
24970 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
24980 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
24990 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
249a0 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
249b0 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d 20 54 68  *.** {F13815} Th
249c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
249d0 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65  n_int(S,N)] inte
249e0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
249f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
24a00 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
24a10 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
24a20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
24a30 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
24a40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24a50 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d  nt] S into a 64-
24a60 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
24a70 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  er and.**       
24a80 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c     returns the l
24a90 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20  ower 32 bits of 
24aa0 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
24ab0 0a 2a 2a 20 7b 46 31 33 38 31 38 7d 20 54 68 65  .** {F13818} The
24ac0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24ad0 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74  _int64(S,N)] int
24ae0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
24af0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24b00 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
24b10 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
24b20 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
24b30 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
24b40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24b50 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34  ent] S into a 64
24b60 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
24b70 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
24b80 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
24b90 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  py of that integ
24ba0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32  er..**.** {F1382
24bb0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
24bc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29  column_text(S,N)
24bd0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
24be0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
24bf0 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
24c00 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
24c10 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
24c20 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
24c30 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
24c40 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
24c50 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
24c60 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20  ed UTF-8 .**    
24c70 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
24c80 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
24c90 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
24ca0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34  g..**.** {F13824
24cb0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
24cc0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e  olumn_text16(S,N
24cd0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
24ce0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
24cf0 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
24d00 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
24d10 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
24d20 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
24d30 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
24d40 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
24d50 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
24d60 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
24d70 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
24d80 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
24d90 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
24da0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
24db0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
24dc0 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
24dd0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 37 7d 20  .**.** {F13827} 
24de0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
24df0 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69  umn_type(S,N)] i
24e00 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65  .**          one
24e20 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   of [SQLITE_NULL
24e30 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ], [SQLITE_INTEG
24e40 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ER], [SQLITE_FLO
24e50 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  AT],.**         
24e60 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
24e70 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  or [SQLITE_BLOB]
24e80 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   as appropriate 
24e90 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
24ea0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69  the Nth column i
24eb0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
24ec0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
24ed0 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
24ee0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
24ef0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
24f00 2a 20 7b 46 31 33 38 33 30 7d 20 54 68 65 20 5b  * {F13830} The [
24f10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
24f20 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  alue(S,N)] inter
24f30 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 0a 2a  face returns a.*
24f40 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
24f50 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74  er to an [unprot
24f60 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
24f70 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20  lue] object for 
24f80 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24f90 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
24fa0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
24fb0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
24fc0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
24fd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24fe0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74  ent] S..*/.const
24ff0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
25000 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
25010 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
25020 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
25030 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
25040 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25050 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
25060 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
25070 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
25080 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
25090 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
250a0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
250b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
250c0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
250d0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
250e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
250f0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
25100 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
25110 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
25120 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
25130 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
25140 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
25150 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
25160 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
25170 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
25180 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
25190 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
251a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
251b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
251c0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
251d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
251e0 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
251f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25200 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
25210 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
25220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25230 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
25240 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
25250 62 6a 65 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a  bject {F13300}.*
25260 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
25270 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
25280 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
25290 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b  o delete a .** [
252a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
252b0 6e 74 5d 2e 20 49 66 20 74 68 65 20 73 74 61 74  nt]. If the stat
252c0 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65  ement was.** exe
252d0 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c  cuted successful
252e0 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 75  ly, or not execu
252f0 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e  ted at all, then
25300 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
25310 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78  turned..** If ex
25320 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  ecution of the s
25330 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20  tatement failed 
25340 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72  then an .** [err
25350 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  or code] or [ext
25360 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
25370 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
25380 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  . .**.** This ro
25390 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
253a0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
253b0 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63   during the exec
253c0 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ution of the.** 
253d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
253e0 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69  ent].  If the vi
253f0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
25400 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65  s not .** comple
25410 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68  ted execution wh
25420 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
25430 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20  is called, that 
25440 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75  is like.** encou
25450 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72  ntering an error
25460 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74   or an interrupt
25470 2e 20 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33  .  (See [sqlite3
25480 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20  _interrupt()].) 
25490 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75  .** Incomplete u
254a0 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f  pdates may be ro
254b0 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72  lled back and tr
254c0 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65  ansactions cance
254d0 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64  led,  .** depend
254e0 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75  ing on the circu
254f0 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68  mstances, and th
25500 65 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  e .** [error cod
25510 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c  e] returned will
25520 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   be [SQLITE_ABOR
25530 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  T]..**.** INVARI
25540 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ANTS:.**.** {F11
25550 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  302} The [sqlite
25560 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
25570 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79  nterface destroy
25580 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
25590 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
255a0 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c  ement] S and rel
255b0 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20  eases all.**    
255c0 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64        memory and
255d0 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20   file resources 
255e0 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a  held by that obj
255f0 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  ect..**.** {F113
25600 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  04} If the most 
25610 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
25620 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
25630 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
25640 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
25650 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
25660 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a  rned an error,.*
25670 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
25680 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
25690 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68  e(S)] returns th
256a0 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a  at same error..*
256b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
256c0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
256d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
256e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
256f0 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
25700 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
25710 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13330}.**.** T
25720 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
25730 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
25740 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
25750 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
25760 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
25770 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 73  ..** back to its
25780 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
25790 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
257a0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  xecuted..** Any 
257b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
257c0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
257d0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
257e0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
257f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
25800 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
25810 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
25820 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
25830 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
25840 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
25850 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
25860 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
25870 2a 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b  * {F11332} The [
25880 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
25890 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
258a0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
258b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
258c0 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
258d0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
258e0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
258f0 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49  **.** {F11334} I
25900 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
25910 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
25920 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
25930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
25940 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25950 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
25960 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
25970 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20  LITE_DONE],.**  
25980 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73          or if [s
25990 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
259a0 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
259b0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
259c0 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  S,.**          t
259d0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
259e0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
259f0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
25a00 2a 20 7b 46 31 31 33 33 36 7d 20 49 66 20 74 68  * {F11336} If th
25a10 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
25a20 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
25a30 74 65 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20  tep(S)] for.**  
25a40 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
25a50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
25a60 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
25a70 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  r, then.**      
25a80 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
25a90 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
25aa0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
25ab0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
25ac0 2a 20 7b 46 31 31 33 33 38 7d 20 54 68 65 20 5b  * {F11338} The [
25ad0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
25ae0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
25af0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
25b00 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
25b10 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74     of any [sqlit
25b20 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
25b30 64 69 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61  dings] on [prepa
25b40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25b50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
25b60 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
25b70 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
25b80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
25b90 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
25ba0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b   SQL Functions {
25bb0 46 31 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F16100}.** KEYWO
25bc0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
25bd0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
25be0 7d 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74  } .**.** These t
25bf0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  wo functions (co
25c00 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
25c10 20 61 73 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e   as.** "function
25c20 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
25c30 65 73 22 29 20 61 72 65 20 75 73 65 64 20 74 6f  es") are used to
25c40 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
25c50 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
25c60 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69  .** or to redefi
25c70 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ne the behavior 
25c80 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
25c90 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
25ca0 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a  regates.  The.**
25cb0 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79   difference only
25cc0 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f   between the two
25cd0 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
25ce0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
25cf0 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  he.** name of th
25d00 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
25d10 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
25d20 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
25d30 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
25d40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25d50 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
25d60 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  6 for sqlite3_cr
25d70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
25d80 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  )..**.** The fir
25d90 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
25da0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
25db0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
25dc0 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
25dd0 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
25de0 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e  added.  If a sin
25df0 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  gle.** program u
25e00 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
25e10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
25e20 65 63 74 69 6f 6e 5d 20 69 6e 74 65 72 6e 61 6c  ection] internal
25e30 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20  ly, then SQL.** 
25e40 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
25e50 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75  e added individu
25e60 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 5b 64 61  ally to each [da
25e70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25e80 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  n]..**.** The se
25e90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
25ea0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
25eb0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
25ec0 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20  o be created.** 
25ed0 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a  or redefined..**
25ee0 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   The length of t
25ef0 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
25f00 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c  ed to 255 bytes,
25f10 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
25f20 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69  e .** zero-termi
25f30 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61  nator.  Note tha
25f40 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74  t the name lengt
25f50 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79  h limit is in by
25f60 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72  tes, not.** char
25f70 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74  acters.  Any att
25f80 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
25f90 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
25fa0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
25fb0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61  will result in a
25fc0 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65  n SQLITE_ERROR e
25fd0 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rror..**.** The 
25fe0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
25ff0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
26000 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
26010 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
26020 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
26030 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20   takes. If this 
26040 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
26050 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
26060 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
26070 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
26080 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
26090 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a   of arguments..*
260a0 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
260b0 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
260c0 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
260d0 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  hat .** [SQLITE_
260e0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
260f0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
26100 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
26110 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
26120 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20  eters.  Any SQL 
26130 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
26140 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  ntation should b
26150 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
26160 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d  * work with UTF-
26170 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
26180 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
26190 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
261a0 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
261b0 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
261c0 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
261d0 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74  han another.  It
261e0 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a   is allowed to.*
261f0 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
26200 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26210 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
26220 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
26230 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
26240 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
26250 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
26260 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
26270 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
26280 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70  ..** When multip
26290 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
262a0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
262b0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
262c0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
262d0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
262e0 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
262f0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
26300 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
26310 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
26320 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
26330 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
26340 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
26350 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65   care what.** te
26360 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  xt encoding is u
26370 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
26380 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
26390 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49  ould be.** [SQLI
263a0 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54  TE_ANY]..**.** T
263b0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
263c0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
263d0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
263e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
263f0 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ** of the functi
26400 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
26410 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
26420 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  er using.** [sql
26430 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
26440 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76  ]..**.** The sev
26450 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64  enth, eighth and
26460 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
26470 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
26480 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
26490 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
264a0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
264b0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
264c0 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  nt the SQL.** fu
264d0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
264e0 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51  ate. A scalar SQ
264f0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
26500 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
26510 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20  ation of.** the 
26520 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f  xFunc callback o
26530 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly, NULL pointe
26540 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  rs should be pas
26550 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
26560 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70  .** and xFinal p
26570 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67  arameters. An ag
26580 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
26590 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
265a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
265b0 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20  ** of xStep and 
265c0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
265d0 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
265e0 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64   for xFunc. To d
265f0 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73  elete an.** exis
26600 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
26610 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
26620 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c  pass NULL for al
26630 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
26640 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
26650 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69  *.** It is permi
26660 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
26670 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
26680 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
26690 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
266a0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
266b0 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
266c0 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
266d0 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
266e0 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
266f0 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
26700 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
26710 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
26720 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
26730 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65  ation most close
26740 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
26750 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
26760 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
26770 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
26780 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
26790 20 7b 46 31 36 31 30 33 7d 20 54 68 65 20 5b 73   {F16103} The [s
267a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
267b0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65  nction16()] inte
267c0 72 66 61 63 65 20 62 65 68 61 76 65 73 20 65 78  rface behaves ex
267d0 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  actly.**        
267e0 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f    like [sqlite3_
267f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
26800 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 20  )] in every way 
26810 65 78 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a  except that it.*
26820 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
26830 70 72 65 74 73 20 74 68 65 20 7a 46 75 6e 63 74  prets the zFunct
26840 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ionName argument
26850 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   as.**          
26860 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
26870 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
26880 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64  te order instead
26890 20 6f 66 20 61 73 20 61 0a 2a 2a 20 20 20 20 20   of as a.**     
268a0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
268b0 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  ated UTF-8..**.*
268c0 2a 20 7b 46 31 36 31 30 36 7d 20 41 20 73 75 63  * {F16106} A suc
268d0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
268e0 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  on of.**        
268f0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    the [sqlite3_c
26900 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
26910 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74  ,X,N,E,...)] int
26920 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
26930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
26940 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63  replaces callbac
26950 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 5b  k functions in [
26960 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26970 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20  ion] D.**       
26980 20 20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65     used to imple
26990 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
269a0 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69  ction named X wi
269b0 74 68 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a  th N parameters.
269c0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
269d0 68 61 76 69 6e 67 20 61 20 70 72 65 66 65 72 72  having a preferr
269e0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
269f0 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   of E..**.** {F1
26a00 36 31 30 39 7d 20 41 20 73 75 63 63 65 73 73 66  6109} A successf
26a10 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
26a20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26a30 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
26a40 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
26a50 20 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 50    replaces the P
26a60 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61  , F, S, and L va
26a70 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72  lues from any pr
26a80 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a  ior calls with.*
26a90 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
26aa0 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64  ame D, X, N, and
26ab0 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a   E values..**.**
26ac0 20 7b 46 31 36 31 31 32 7d 20 54 68 65 20 5b 73   {F16112} The [s
26ad0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26ae0 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d  nction(D,X,...)]
26af0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
26b00 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
26b10 20 20 61 20 72 65 74 75 72 6e 20 63 6f 64 65 20    a return code 
26b20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  of [SQLITE_ERROR
26b30 5d 20 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e  ] if the SQL fun
26b40 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a  ction name X is.
26b50 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67  **          long
26b60 65 72 20 74 68 61 6e 20 32 35 35 20 62 79 74 65  er than 255 byte
26b70 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  s exclusive of t
26b80 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
26b90 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31  or..**.** {F1611
26ba0 38 7d 20 45 69 74 68 65 72 20 46 20 6d 75 73 74  8} Either F must
26bb0 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61   be NULL and S a
26bc0 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c  nd L are non-NUL
26bd0 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20  L or else F.**  
26be0 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e          is non-N
26bf0 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20  ULL and S and L 
26c00 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77  are NULL, otherw
26c10 69 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ise.**          
26c20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
26c30 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
26c40 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72  ,P,F,S,L)] retur
26c50 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ns [SQLITE_ERROR
26c60 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 31  ]..**.** {F16121
26c70 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
26c80 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
26c90 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
26ca0 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
26cb0 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72  *          error
26cc0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
26cd0 5f 42 55 53 59 5d 20 69 66 20 74 68 65 72 65 20  _BUSY] if there 
26ce0 65 78 69 73 74 20 5b 70 72 65 70 61 72 65 64 20  exist [prepared 
26cf0 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20  statements].**  
26d00 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74          associat
26d10 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
26d20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26d30 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  ] D..**.** {F161
26d40 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
26d50 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26d60 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74  (D,X,N,...)] int
26d70 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
26d80 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  h an.**         
26d90 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
26da0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
26db0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 28 73 70   parameter N (sp
26dc0 65 63 69 66 79 69 6e 67 20 74 68 65 20 6e 75 6d  ecifying the num
26dd0 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ber.**          
26de0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  of arguments to 
26df0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
26e00 20 62 65 69 6e 67 20 72 65 67 69 73 74 65 72 65   being registere
26e10 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20  d) is less.**   
26e20 20 20 20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f         than -1 o
26e30 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
26e40 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32  27..**.** {F1612
26e50 37 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e  7} When N is non
26e60 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b  -negative, the [
26e70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26e80 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
26e90 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
26ea0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
26eb0 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65   callbacks to be
26ec0 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65   invoked for the
26ed0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL function.**
26ee0 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20            named 
26ef0 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65  X when the numbe
26f00 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
26f10 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
26f20 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  on is.**        
26f30 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a    exactly N..**.
26f40 2a 2a 20 7b 46 31 36 31 33 30 7d 20 57 68 65 6e  ** {F16130} When
26f50 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73   N is -1, the [s
26f60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26f70 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e  nction(D,X,N,...
26f80 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
26f90 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
26fa0 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20  callbacks to be 
26fb0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20  invoked for the 
26fc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  SQL function.** 
26fd0 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58           named X
26fe0 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72   with any number
26ff0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a   of arguments..*
27000 2a 0a 2a 2a 20 7b 46 31 36 31 33 33 7d 20 57 68  *.** {F16133} Wh
27010 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  en calls to [sql
27020 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
27030 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
27040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65  .**          spe
27050 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d  cify multiple im
27060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
27070 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
27080 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20  on X.**         
27090 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d   and when one im
270a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73  plementation has
270b0 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74   N>=0 and the ot
270c0 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a  her has N=(-1).*
270d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69  *          the i
270e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
270f0 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20  th a non-zero N 
27100 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a  is preferred..**
27110 0a 2a 2a 20 7b 46 31 36 31 33 36 7d 20 57 68 65  .** {F16136} Whe
27120 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
27130 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27140 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29  ion(D,X,N,E,...)
27150 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70  ].**          sp
27160 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69  ecify multiple i
27170 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
27180 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
27190 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20  ion X with.**   
271a0 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
271b0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
271c0 6e 74 73 20 4e 20 62 75 74 20 77 69 74 68 20 64  nts N but with d
271d0 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20  ifferent.**     
271e0 20 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45       encodings E
271f0 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65  , then the imple
27200 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20  mentation where 
27210 45 20 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a  E matches the.**
27220 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
27230 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 70  se encoding is p
27240 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  referred..**.** 
27250 7b 46 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20  {F16139} For an 
27260 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
27270 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75  nction created u
27280 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
27290 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
272a0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
272b0 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20  E,P,0,S,L)] the 
272c0 66 69 6e 69 61 6c 69 7a 65 72 0a 2a 2a 20 20 20  finializer.**   
272d0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
272e0 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65  L will always be
272f0 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79   invoked exactly
27300 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20   once if the.** 
27310 20 20 20 20 20 20 20 20 20 73 74 65 70 20 66 75           step fu
27320 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c  nction S is call
27330 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
27340 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  imes..**.** {F16
27350 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 65  142} When SQLite
27360 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 20   invokes either 
27370 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 53 74  the xFunc or xSt
27380 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a  ep function of.*
27390 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 61 70  *          an ap
273a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
273b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  d SQL function o
273c0 72 20 61 67 67 72 65 67 61 74 65 20 63 72 65 61  r aggregate crea
273d0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
273e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  by [sqlite3_crea
273f0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f  te_function()] o
27400 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
27410 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
27420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
27430 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66 20 5b  n the array of [
27440 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
27450 62 6a 65 63 74 73 20 70 61 73 73 65 64 20 61 73  bjects passed as
27460 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27470 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
27480 20 61 72 65 20 61 6c 77 61 79 73 20 5b 70 72 6f   are always [pro
27490 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
274a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
274b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
274c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
274d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
274e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
274f0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
27500 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
27510 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
27520 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
27530 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
27540 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
27550 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
27560 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
27570 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
27580 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
27590 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
275a0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
275b0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
275c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
275d0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
275e0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
275f0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
27600 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
27610 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
27620 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
27630 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
27640 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
27650 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
27660 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
27670 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
27680 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
27690 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
276a0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
276b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
276c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
276d0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
276e0 73 20 7b 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a  s {F10267}.**.**
276f0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
27700 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
27710 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
27720 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
27730 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
27740 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
27750 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
27760 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
27770 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
27780 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
27790 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
277a0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
277b0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
277c0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
277d0 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
277e0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
277f0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
27800 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
27810 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
27820 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27830 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
27840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
27850 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
27860 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
27870 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
27880 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
27890 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20  I3REF: Obsolete 
278a0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
278b0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
278c0 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f  are all now obso
278d0 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20  lete.  In order 
278e0 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
278f0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
27900 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
27910 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69  r code, we conti
27920 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a  nue to support.*
27930 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
27940 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  s.  However, new
27950 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f   development pro
27960 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f  jects should avo
27970 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
27980 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
27990 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
279a0 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
279b0 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
279c0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
279d0 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
279e0 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74  to tell you want
279f0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74   they do..*/.int
27a00 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
27a10 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
27a20 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20  _context*);.int 
27a30 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
27a40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
27a50 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
27a60 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
27a70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
27a80 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
27a90 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
27aa0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76  recover(void);.v
27ab0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
27ac0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
27ad0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  ;.int sqlite3_me
27ae0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
27af0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
27b00 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
27b10 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
27b20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27b30 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
27b40 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
27b50 74 65 72 20 56 61 6c 75 65 73 20 7b 46 31 35 31  ter Values {F151
27b60 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  00}.**.** The C-
27b70 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
27b80 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
27b90 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
27ba0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
27bb0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
27bc0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
27bd0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
27be0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
27bf0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
27c00 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
27c10 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
27c20 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
27c30 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
27c40 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
27c50 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
27c60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
27c70 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
27c80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
27c90 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
27ca0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
27cb0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
27cc0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
27cd0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
27ce0 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
27cf0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
27d00 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
27d10 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
27d20 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
27d30 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27d40 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
27d50 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
27d60 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
27d70 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
27d80 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
27d90 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
27da0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
27db0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
27dc0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
27dd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
27de0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
27df0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
27e00 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
27e10 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
27e20 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
27e30 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
27e40 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
27e50 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
27e60 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
27e70 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
27e80 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
27e90 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
27ea0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
27eb0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
27ec0 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
27ed0 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73  esponding .** [s
27ee0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
27ef0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ob | sqlite3_col
27f00 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20  umn_* routines] 
27f10 65 78 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20  except that .** 
27f20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
27f30 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
27f40 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27f50 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 70 6f  value] object po
27f60 69 6e 74 65 72 0a 2a 2a 20 69 6e 73 74 65 61 64  inter.** instead
27f70 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
27f80 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
27f90 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
27fa0 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
27fb0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
27fc0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
27fd0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
27fe0 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a  a UTF16 string.*
27ff0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
28000 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
28010 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
28020 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
28030 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
28040 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
28050 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
28060 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
28070 61 63 74 20 55 54 46 31 36 20 73 74 72 69 6e 67  act UTF16 string
28080 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
28090 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
280a0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
280b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
280c0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
280d0 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
280e0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
280f0 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
28100 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
28110 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
28120 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
28130 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
28140 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
28150 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
28160 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
28170 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
28180 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
28190 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
281a0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
281b0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
281c0 77 6f 72 64 73 20 69 66 20 74 68 65 20 76 61 6c  words if the val
281d0 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
281e0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
281f0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
28200 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
28210 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77  is done.  Otherw
28220 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
28230 6e 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 0a  n occurs.  The .
28240 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
28250 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
28260 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
28270 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
28280 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
28290 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
282a0 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
282b0 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
282c0 74 68 61 74 0a 2a 2a 20 69 73 20 72 65 74 75 72  that.** is retur
282d0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
282e0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
282f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28300 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
28310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28320 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
28330 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
28340 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
28350 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
28360 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
28370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
28380 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
28390 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
283a0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
283b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
283c0 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .  .**.** These 
283d0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
283e0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
283f0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
28400 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
28410 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
28420 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
28430 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
28440 73 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  s..**.**.** INVA
28450 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
28460 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  15103} The [sqli
28470 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56  te3_value_blob(V
28480 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
28490 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
284a0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
284b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
284c0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
284d0 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65  blob and then re
284e0 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20  turns a.**      
284f0 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74      pointer to t
28500 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c  he converted val
28510 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30  ue..**.** {F1510
28520 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
28530 76 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20  value_bytes(V)] 
28540 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28550 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
28560 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
28570 73 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72  s in the blob or
28580 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
28590 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
285a0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
285b0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
285c0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
285d0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
285e0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
285f0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
28600 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
28610 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  b(V)] or.**     
28620 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
28630 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a  lue_text(V)]..**
28640 0a 2a 2a 20 7b 46 31 35 31 30 39 7d 20 54 68 65  .** {F15109} The
28650 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28660 62 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65  bytes16(V)] inte
28670 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
28680 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
28690 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
286a0 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63   the string (exc
286b0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
286c0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
286d0 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
286e0 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
286f0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
28700 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
28710 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
28720 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  o [sqlite3_value
28730 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20  _text16(V)],.** 
28740 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
28750 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
28760 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  (V)], or [sqlite
28770 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
28780 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  (V)]..**.** {F15
28790 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  112} The [sqlite
287a0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56  3_value_double(V
287b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
287c0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
287d0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
287e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
287f0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
28800 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
28810 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  alue and.**     
28820 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
28830 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75  opy of that valu
28840 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35  e..**.** {F15115
28850 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
28860 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74  alue_int(V)] int
28870 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
28880 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
28890 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
288a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
288b0 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   V into a 64-bit
288c0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
288d0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
288e0 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65  returns the lowe
288f0 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61  r 32 bits of tha
28900 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
28910 20 7b 46 31 35 31 31 38 7d 20 54 68 65 20 5b 73   {F15118} The [s
28920 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
28930 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  64(V)] interface
28940 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
28950 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
28960 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28970 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
28980 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
28990 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
289a0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
289b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
289c0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
289d0 7b 46 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71  {F15121} The [sq
289e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
289f0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
28a00 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
28a10 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
28a20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28a30 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
28a40 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
28a50 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20  d UTF-8 .**     
28a60 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
28a70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
28a80 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
28a90 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d  ..**.** {F15124}
28aa0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
28ab0 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69  lue_text16(V)] i
28ac0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
28ad0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
28ae0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
28af0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
28b00 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
28b10 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
28b20 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
28b30 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61  ligned UTF-16 na
28b40 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
28b50 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
28b60 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
28b70 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
28b80 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
28b90 46 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c  F15127} The [sql
28ba0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
28bb0 36 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  6be(V)] interfac
28bc0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
28bd0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
28be0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28bf0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
28c00 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
28c10 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
28c20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
28c30 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
28c40 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
28c50 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
28c60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
28c70 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
28c80 20 7b 46 31 35 31 33 30 7d 20 54 68 65 20 5b 73   {F15130} The [s
28c90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
28ca0 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66  t16le(V)] interf
28cb0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
28cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
28cd0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28ce0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
28cf0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
28d00 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
28d10 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
28d20 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  d UTF-16 little-
28d30 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
28d40 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
28d50 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
28d60 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
28d70 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54  **.** {F15133} T
28d80 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
28d90 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72  e_type(V)] inter
28da0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
28db0 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20           one of 
28dc0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b  [SQLITE_NULL], [
28dd0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
28de0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
28df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
28e00 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b  LITE_TEXT], or [
28e10 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
28e20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
28e30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
28e40 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
28e50 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20  object V..**.** 
28e60 7b 46 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71  {F15136} The [sq
28e70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
28e80 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74  ric_type(V)] int
28e90 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a  erface converts.
28ea0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
28eb0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
28ec0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
28ed0 20 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61   V into either a
28ee0 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20  n integer or.** 
28ef0 20 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74           a float
28f00 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
28f10 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20  if it can do so 
28f20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a  without loss of.
28f30 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f  **          info
28f40 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74  rmation, and ret
28f50 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  urns one of [SQL
28f60 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20  ITE_NULL],.**   
28f70 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
28f80 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
28f90 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
28fa0 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20  _TEXT], or.**   
28fb0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42         [SQLITE_B
28fc0 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
28fd0 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ate for.**      
28fe0 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74      the [protect
28ff0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29000 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72  ] object V after
29010 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
29020 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73  attempt..*/.cons
29030 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29040 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
29050 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
29060 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
29070 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
29080 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
29090 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
290a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
290b0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
290c0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
290d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
290e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
290f0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
29100 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
29110 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
29120 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
29130 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
29140 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
29150 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
29160 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
29170 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
29180 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
29190 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
291a0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
291b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
291c0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
291d0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
291e0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
291f0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
29200 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
29210 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
29220 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
29230 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
29240 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
29250 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
29260 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29270 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
29280 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
29290 74 65 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a  text {F16210}.**
292a0 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
292b0 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67  tation of aggreg
292c0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
292d0 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  s use this routi
292e0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a  ne to allocate.*
292f0 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f  * a structure fo
29300 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
29310 73 74 61 74 65 2e 20 20 0a 2a 2a 20 54 68 65 20  state.  .** The 
29320 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
29330 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29340 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69  _context() routi
29350 6e 65 20 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c  ne is.** is call
29360 65 64 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ed for a particu
29370 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53  lar aggregate, S
29380 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20  QLite allocates 
29390 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79  nBytes of memory
293a0 0a 2a 2a 20 7a 65 72 6f 73 20 74 68 61 74 20 6d  .** zeros that m
293b0 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
293c0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
293d0 69 74 2e 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64  it..** On second
293e0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
293f0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
29400 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
29410 78 74 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  xt().** for the 
29420 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
29430 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 20 74  unction index, t
29440 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
29450 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54  s returned..** T
29460 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
29470 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72  n.** of the aggr
29480 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68  egate can use th
29490 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65  e returned buffe
294a0 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20  r to accumulate 
294b0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  data..**.** SQLi
294c0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
294d0 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63   frees the alloc
294e0 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e  ated buffer when
294f0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
29500 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  * query conclude
29510 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
29520 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  st parameter sho
29530 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66  uld be a copy of
29540 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
29550 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
29560 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
29570 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
29580 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
29590 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
295a0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
295b0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
295c0 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
295d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
295e0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
295f0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
29600 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
29610 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
29620 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
29630 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
29640 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
29650 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54  **.** {F16211} T
29660 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74  he first invocat
29670 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
29680 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
29690 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20  t(C,N)] for.**  
296a0 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69 63          a partic
296b0 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66  ular instance of
296c0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 75   an aggregate fu
296d0 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61  nction (for a pa
296e0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20  rticular.**     
296f0 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20       context C) 
29700 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
29710 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 4e 20 62 79   allocation N by
29720 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a  tes of memory,.*
29730 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
29740 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
29750 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65   return a pointe
29760 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74  r to the allocat
29770 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ed.**          m
29780 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  emory..**.** {F1
29790 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72  6213} If a memor
297a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
297b0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
297c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
297d0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
297e0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68  context(C,N)] th
297f0 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
29800 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a  returns 0..**.**
29810 20 7b 46 31 36 32 31 35 7d 20 53 65 63 6f 6e 64   {F16215} Second
29820 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
29830 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a  invocations of.*
29840 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
29850 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
29860 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20  ntext(C,N)] for 
29870 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74  the same context
29880 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20   pointer C.**   
29890 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68         ignore th
298a0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e  e N parameter an
298b0 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  d return a point
298c0 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a  er to the same.*
298d0 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b  *          block
298e0 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72   of memory retur
298f0 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ned by the first
29900 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
29910 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54 68 65 20  ** {F16217} The 
29920 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
29930 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67   by [sqlite3_agg
29940 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
29950 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20  ,N)] is.**      
29960 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c      automaticall
29970 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e  y freed on the n
29980 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ext call to [sql
29990 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
299a0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
299b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
299c0 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  ] for the [prepa
299d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63  red statement] c
299e0 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20  ontaining.**    
299f0 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65 67        the aggreg
29a00 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  ate function ass
29a10 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e  ociated with con
29a20 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20  text C..*/.void 
29a30 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
29a40 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
29a50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
29a60 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
29a70 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
29a80 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
29a90 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a  ns {F16240}.**.*
29aa0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73  * The sqlite3_us
29ab0 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
29ac0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
29ad0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
29ae0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
29af0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
29b00 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
29b10 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
29b20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
29b30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
29b40 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
29b50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
29b60 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
29b70 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
29b80 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
29b90 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
29ba0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45  ned function. {E
29bb0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ND}.**.** This r
29bc0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
29bd0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
29be0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
29bf0 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
29c00 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
29c10 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
29c20 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ng..**.** INVARI
29c30 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
29c40 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  243} The [sqlite
29c50 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29 5d 20  3_user_data(C)] 
29c60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29c70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
29c80 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20 70 6f  **          P po
29c90 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b  inter from the [
29ca0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29cb0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
29cc0 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20  P,F,S,L)].**    
29cd0 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
29ce0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29cf0 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  n16(D,X,N,E,P,F,
29d00 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a  S,L)] call that.
29d10 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
29d20 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66  stered the SQL f
29d30 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74  unction associat
29d40 65 64 20 77 69 74 68 20 0a 2a 2a 20 20 20 20 20  ed with .**     
29d50 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
29d60 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69  ntext] C..*/.voi
29d70 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
29d80 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
29d90 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
29da0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
29db0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
29dc0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32   Functions {F162
29dd0 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  50}.**.** The sq
29de0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
29df0 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
29e00 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
29e10 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
29e20 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
29e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29e40 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
29e50 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
29e60 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
29e70 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
29e80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
29e90 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
29ea0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
29eb0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
29ec0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
29ed0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
29ee0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
29ef0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
29f00 2a 20 7b 46 31 36 32 35 33 7d 20 54 68 65 20 5b  * {F16253} The [
29f10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
29f20 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e  db_handle(C)] in
29f30 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29f40 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
29f50 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e            D poin
29f60 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
29f70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29f80 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
29f90 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
29fa0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
29fb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
29fc0 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
29fd0 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
29fe0 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
29ff0 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
2a000 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
2a010 20 77 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20   with .**       
2a020 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74     [sqlite3_cont
2a030 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74  ext] C..*/.sqlit
2a040 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
2a050 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
2a060 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2a070 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a080 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
2a090 69 61 72 79 20 44 61 74 61 20 7b 46 31 36 32 37  iary Data {F1627
2a0a0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  0}.**.** The fol
2a0b0 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
2a0c0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
2a0d0 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
2a0e0 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
2a0f0 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64 61  ssociate meta-da
2a100 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
2a110 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
2a120 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
2a130 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
2a140 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
2a150 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
2a160 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
2a170 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
2a180 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
2a190 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
2a1a0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
2a1b0 2d 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  -data may be pre
2a1c0 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
2a1d0 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
2a1e0 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
2a1f0 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
2a200 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
2a210 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
2a220 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
2a230 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
2a240 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2a250 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
2a260 2a 20 6d 65 74 61 2d 64 61 74 61 20 61 73 73 6f  * meta-data asso
2a270 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2a280 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64  SQL value passed
2a290 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20   as the regular 
2a2a0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61  expression.** pa
2a2b0 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70  ttern.  The comp
2a2c0 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
2a2d0 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
2a2e0 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
2a2f0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
2a300 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2a310 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68  ction so that th
2a320 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65  e original patte
2a330 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65  rn string.** doe
2a340 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2a350 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65   recompiled on e
2a360 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  ach invocation..
2a370 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2a380 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
2a390 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a3a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2a3b0 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20  he meta-data.** 
2a3c0 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
2a3d0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
2a3e0 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
2a3f0 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
2a400 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
2a410 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
2a420 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2a430 69 6f 6e 2e 0a 2a 2a 20 49 66 20 6e 6f 20 6d 65  ion..** If no me
2a440 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65 6e  ta-data has been
2a450 20 65 76 65 72 20 62 65 65 6e 20 73 65 74 20 66   ever been set f
2a460 6f 72 20 74 68 65 20 4e 74 68 0a 2a 2a 20 61 72  or the Nth.** ar
2a470 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
2a480 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
2a490 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2a4a0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2a4b0 65 72 0a 2a 2a 20 68 61 73 20 63 68 61 6e 67 65  er.** has change
2a4c0 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
2a4d0 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 20 74  -data was set, t
2a4e0 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hen sqlite3_get_
2a4f0 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 72 65 74  auxdata().** ret
2a500 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
2a510 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
2a520 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2a530 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
2a540 61 76 65 73 20 74 68 65 20 6d 65 74 61 2d 64 61  aves the meta-da
2a550 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
2a560 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
2a570 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
2a580 61 2d 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  a-data for the N
2a590 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
2a5a0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2a5b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2a5c0 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
2a5d0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2a5e0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2a5f0 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
2a600 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
2a610 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
2a620 20 64 65 73 74 72 6f 79 65 64 2e 20 0a 2a 2a 20   destroyed. .** 
2a630 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
2a640 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
2a650 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2a660 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63 74 69 6f  ctor .** functio
2a670 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
2a680 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2a690 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2a6a0 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
2a6b0 6d 65 74 61 2d 64 61 74 61 20 77 68 65 6e 20 74  meta-data when t
2a6c0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2a6d0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
2a6e0 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
2a6f0 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
2a700 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
2a710 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
2a720 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
2a730 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
2a740 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
2a750 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
2a760 6d 65 74 61 2d 64 61 74 61 20 6f 6e 0a 2a 2a 20  meta-data on.** 
2a770 61 6e 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  any parameter of
2a780 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
2a790 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20   any time.  The 
2a7a0 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 0a 2a  only guarantee.*
2a7b0 2a 20 69 73 20 74 68 61 74 20 74 68 65 20 64 65  * is that the de
2a7c0 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
2a7d0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
2a7e0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 0a 2a  he metadata is.*
2a7f0 2a 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  * dropped..**.**
2a800 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
2a810 74 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65  ta-data is prese
2a820 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
2a830 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
2a840 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
2a850 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
2a860 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
2a870 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
2a880 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
2a890 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62  s and SQL variab
2a8a0 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  les..**.** These
2a8b0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
2a8c0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2a8d0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2a8e0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
2a8f0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2a900 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  nning..**.** INV
2a910 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2a920 46 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c  F16272} The [sql
2a930 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2a940 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,N)] interface
2a950 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2a960 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
2a970 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
2a980 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e  iated with the N
2a990 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
2a9a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2a9b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f  .**          who
2a9c0 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c  se context is C,
2a9d0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72   or NULL if ther
2a9e0 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61  e is no metadata
2a9f0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20   associated.**  
2aa00 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 61          with tha
2aa10 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
2aa20 2a 2a 20 7b 46 31 36 32 37 34 7d 20 54 68 65 20  ** {F16274} The 
2aa30 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2aa40 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
2aa50 6e 74 65 72 66 61 63 65 20 61 73 73 69 67 6e 73  nterface assigns
2aa60 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20   a metadata.**  
2aa70 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
2aa80 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72  P to the Nth par
2aa90 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
2aaa0 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  L function with 
2aab0 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  context.**      
2aac0 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31      C..**.** {F1
2aad0 36 32 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c  6276} SQLite wil
2aae0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
2aaf0 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61  tructor D with a
2ab00 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
2ab10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
2ab20 63 68 20 69 73 20 74 68 65 20 6d 65 74 61 64 61  ch is the metada
2ab30 74 61 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c  ta pointer P fol
2ab40 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
2ab50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2ab60 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2ab70 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e  a(C,N,P,D)] when
2ab80 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74   SQLite ceases t
2ab90 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20  o hold.**       
2aba0 20 20 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e     the metadata.
2abb0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 37 7d 20  .**.** {F16277} 
2abc0 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f  SQLite ceases to
2abd0 20 68 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66   hold metadata f
2abe0 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  or an SQL functi
2abf0 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  on parameter.** 
2ac00 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 74 68           when th
2ac10 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
2ac20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
2ac30 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 38  s..**.** {F16278
2ac40 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  } When [sqlite3_
2ac50 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
2ac60 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  P,D)] is invoked
2ac70 2c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  , the destructor
2ac80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2ac90 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70  called for any p
2aca0 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73  rior metadata as
2acb0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2acc0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
2acd0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
2ace0 65 78 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65  ext C and parame
2acf0 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ter N..**.** {F1
2ad00 36 32 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c  6279} SQLite wil
2ad10 6c 20 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f  l call destructo
2ad20 72 73 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64  rs for any metad
2ad30 61 74 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e  ata it is holdin
2ad40 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  g.**          in
2ad50 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70   a particular [p
2ad60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ad70 74 5d 20 53 20 77 68 65 6e 20 65 69 74 68 65 72  t] S when either
2ad80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2ad90 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2ada0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2adb0 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
2adc0 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ed..*/.void *sql
2add0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2ade0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2adf0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
2ae00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2ae10 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2ae20 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
2ae30 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
2ae40 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
2ae50 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
2ae60 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
2ae70 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
2ae80 68 61 76 69 6f 72 20 7b 46 31 30 32 38 30 7d 0a  havior {F10280}.
2ae90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
2aea0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 66 6f  special value fo
2aeb0 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
2aec0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
2aed0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
2aee0 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
2aef0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2af00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2af10 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65  b()].  If the de
2af20 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
2af30 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
2af40 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
2af50 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
2af60 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
2af70 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
2af80 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
2af90 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
2afa0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
2afb0 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49 54  .  The .** SQLIT
2afc0 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
2afd0 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
2afe0 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
2aff0 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
2b000 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
2b010 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
2b020 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
2b030 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2b040 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
2b050 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
2b060 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
2b070 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
2b080 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
2b090 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
2b0a0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
2b0b0 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
2b0c0 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
2b0d0 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
2b0e0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2b0f0 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
2b100 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b110 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
2b120 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2b130 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
2b140 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
2b150 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
2b160 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
2b170 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
2b180 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
2b190 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
2b1a0 46 75 6e 63 74 69 6f 6e 20 7b 46 31 36 34 30 30  Function {F16400
2b1b0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
2b1c0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
2b1d0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
2b1e0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
2b1f0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
2b200 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
2b210 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
2b220 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
2b230 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b240 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
2b250 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b260 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
2b270 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2b280 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
2b290 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
2b2a0 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
2b2b0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
2b2c0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
2b2d0 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d  ite3_bind_*] fam
2b2e0 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
2b2f0 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64   used.** to bind
2b300 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
2b310 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
2b320 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b330 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
2b340 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
2b350 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
2b360 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65  e3_bind_* docume
2b370 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20  ntation] for.** 
2b380 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
2b390 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
2b3a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b3b0 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
2b3c0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2b3d0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
2b3e0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2b3f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2b400 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
2b410 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
2b420 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
2b430 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2b440 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
2b450 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
2b460 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
2b470 64 20 70 61 72 61 6d 65 74 65 72 2e 20 0a 2a 2a  d parameter. .**
2b480 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2b490 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
2b4a0 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
2b4b0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2b4c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2b4d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2b4e0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
2b4f0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
2b500 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
2b510 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
2b520 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
2b530 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
2b540 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2b550 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2b560 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
2b570 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2b580 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
2b590 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2b5a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2b5b0 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
2b5c0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
2b5d0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
2b5e0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
2b5f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2b600 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2b610 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2b620 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
2b630 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
2b640 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
2b650 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
2b660 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
2b670 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  ..** SQLite uses
2b680 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
2b690 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
2b6a0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
2b6b0 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
2b6c0 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
2b6d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b6e0 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
2b6f0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
2b700 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65  message.  SQLite
2b710 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2b720 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2b730 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
2b740 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b750 72 28 29 20 61 73 20 55 54 46 38 2e 20 53 51 4c  r() as UTF8. SQL
2b760 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
2b770 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
2b780 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
2b790 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
2b7a0 46 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  F16 in native.**
2b7b0 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66   byte order.  If
2b7c0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2b7d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2b7e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
2b7f0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2b800 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
2b810 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
2b820 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
2b830 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
2b840 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
2b850 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
2b860 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
2b870 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72  ..** If the thir
2b880 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2b890 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b8a0 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
2b8b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b8c0 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
2b8d0 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
2b8e0 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
2b8f0 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
2b900 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
2b910 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2b920 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
2b930 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73  essage..** The s
2b940 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b950 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
2b960 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2b970 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
2b980 61 6b 65 20 61 20 63 6f 70 79 20 70 72 69 76 61  ake a copy priva
2b990 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
2b9a0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
2b9b0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
2b9c0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
2b9d0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
2b9e0 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
2b9f0 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
2ba00 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
2ba10 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
2ba20 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68  hout harm..** Th
2ba30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ba40 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
2ba50 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
2ba60 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
2ba70 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
2ba80 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
2ba90 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
2baa0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64   function.  By d
2bab0 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
2bac0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
2bad0 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75  ITE_ERROR.  A su
2bae0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
2baf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bb00 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
2bb10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2bb20 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
2bb30 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
2bb40 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
2bb50 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2bb60 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
2bb70 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2bb80 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74 68   SQLite.** to th
2bb90 72 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 6e 64  row an error ind
2bba0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
2bbb0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
2bbc0 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72   to long.** to r
2bbd0 65 70 72 65 73 65 6e 74 2e 20 20 54 68 65 20 73  epresent.  The s
2bbe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
2bbf0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 0a  mem() interface.
2bc00 2a 2a 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ** causes SQLite
2bc10 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
2bc20 65 70 74 69 6f 6e 20 69 6e 64 69 63 61 74 69 6e  eption indicatin
2bc30 67 20 74 68 61 74 20 74 68 65 20 61 0a 2a 2a 20  g that the a.** 
2bc40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2bc50 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
2bc60 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2bc70 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
2bc80 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2bc90 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2bca0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2bcb0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2bcc0 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
2bcd0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2bce0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
2bcf0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
2bd00 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  nt..** The sqlit
2bd10 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2bd20 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2bd30 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2bd40 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2bd50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2bd60 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2bd70 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
2bd80 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
2bd90 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
2bda0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
2bdb0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2bdc0 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
2bdd0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2bde0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2bdf0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2be00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2be10 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
2be20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2be30 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
2be40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2be50 74 65 78 74 31 36 28 29 2c 20 0a 2a 2a 20 73 71  text16(), .** sq
2be60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2be70 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
2be80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2be90 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
2bea0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
2beb0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
2bec0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2bed0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2bee0 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
2bef0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
2bf00 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
2bf10 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
2bf20 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
2bf30 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
2bf40 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
2bf50 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
2bf60 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51  pectively..** SQ
2bf70 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
2bf80 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
2bf90 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2bfa0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
2bfb0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2bfc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bfd0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2bfe0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
2bff0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2c000 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c010 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2c020 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
2c030 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2c040 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
2c050 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
2c060 6d 65 74 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67  meter .** throug
2c070 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
2c080 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
2c090 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
2c0a0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2c0b0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2c0c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2c0d0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
2c0e0 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
2c0f0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
2c100 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
2c110 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
2c120 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2c130 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
2c140 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2c150 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
2c160 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  on result..** If
2c170 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2c180 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2c190 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2c1a0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
2c1b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2c1c0 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
2c1d0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
2c1e0 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
2c1f0 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
2c200 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2c210 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 62  on the text or b
2c220 6c 6f 62 20 72 65 73 75 6c 74 20 77 68 65 6e 20  lob result when 
2c230 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
2c240 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
2c250 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20  sult..** If the 
2c260 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2c270 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2c280 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2c290 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
2c2a0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2c2b0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
2c2c0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
2c2d0 41 54 49 43 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ATIC, then.** SQ
2c2e0 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2c2f0 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 62 6c  t the text or bl
2c300 6f 62 20 72 65 73 75 6c 74 20 69 73 20 63 6f 6e  ob result is con
2c310 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 0a  stant space and.
2c320 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 63 6f 70 79  ** does not copy
2c330 20 74 68 65 20 73 70 61 63 65 20 6f 72 20 63 61   the space or ca
2c340 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
2c350 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
2c360 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
2c370 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  at result..** If
2c380 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2c390 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2c3a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2c3b0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
2c3c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2c3d0 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2c3e0 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2c3f0 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
2c400 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
2c410 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2c420 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
2c430 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
2c440 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2c450 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
2c460 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
2c470 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2c480 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2c490 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2c4a0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2c4b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2c4c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2c4d0 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
2c4e0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2c4f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2c500 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
2c510 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2c520 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73  meter.  The.** s
2c530 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2c540 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
2c550 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
2c560 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2c570 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 5b  ue].** so that [
2c580 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
2c590 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
2c5a0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
2c5b0 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
2c5c0 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
2c5d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2c5e0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
2c5f0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2c600 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
2c610 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c620 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
2c630 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
2c640 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2c650 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2c660 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
2c670 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
2c680 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
2c690 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
2c6a0 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
2c6b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
2c6c0 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
2c6d0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2c6e0 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
2c6f0 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
2c700 61 64 20 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ad .** than the 
2c710 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
2c720 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2c730 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2c740 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
2c750 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2c760 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
2c770 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2c780 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2c790 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2c7a0 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54 68 65 20  ** {F16403} The 
2c7b0 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76  default return v
2c7c0 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51  alue from any SQ
2c7d0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55  L function is NU
2c7e0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30  LL..**.** {F1640
2c7f0 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
2c800 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
2c810 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
2c820 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
2c830 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
2c840 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2c850 20 43 20 74 6f 20 62 65 20 61 20 62 6c 6f 62 20   C to be a blob 
2c860 74 68 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a  that is N bytes.
2c870 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c  **          in l
2c880 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20 63  ength and with c
2c890 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74  ontent pointed t
2c8a0 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  o by V..**.** {F
2c8b0 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  16409} The [sqli
2c8c0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2c8d0 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  e(C,V)] interfac
2c8e0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
2c8f0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2c900 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2c910 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 66  on C to be the f
2c920 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2c930 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lue V..**.** {F1
2c940 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6412} The [sqlit
2c950 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2c960 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  C,V,N)] interfac
2c970 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
2c980 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2c990 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2c9a0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
2c9b0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
2c9c0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
2c9d0 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
2c9e0 52 5d 20 61 6e 64 20 61 20 55 54 46 38 20 65 72  R] and a UTF8 er
2c9f0 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69  ror message copi
2ca00 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20  ed from V up to 
2ca10 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2ca20 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20  first zero byte 
2ca30 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
2ca40 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
2ca50 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
2ca60 2a 20 7b 46 31 36 34 31 35 7d 20 54 68 65 20 5b  * {F16415} The [
2ca70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2ca80 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69  rror16(C,V,N)] i
2ca90 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2caa0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
2cab0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
2cac0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2cad0 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
2cae0 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  ith error code.*
2caf0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
2cb00 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20  TE_ERROR] and a 
2cb10 55 54 46 31 36 20 6e 61 74 69 76 65 20 62 79 74  UTF16 native byt
2cb20 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d 65  e order error me
2cb30 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  ssage.**        
2cb40 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20    copied from V 
2cb50 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2cb60 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2cb70 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
2cb80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
2cb90 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f   read if N is po
2cba0 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sitive..**.** {F
2cbb0 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  16418} The [sqli
2cbc0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2cbd0 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65  _toobig(C)] inte
2cbe0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2cbf0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
2cc00 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
2cc10 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
2cc20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
2cc30 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
2cc40 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2cc50 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20  ITE_TOOBIG] and 
2cc60 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
2cc70 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
2cc80 0a 2a 2a 20 7b 46 31 36 34 32 31 7d 20 54 68 65  .** {F16421} The
2cc90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2cca0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d  _error_nomem(C)]
2ccb0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2ccc0 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
2ccd0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
2cce0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
2ccf0 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
2cd00 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
2cd10 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
2cd20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
2cd30 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61  and an appropria
2cd40 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
2cd50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 34 7d  ..**.** {F16424}
2cd60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2cd70 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
2cd80 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,E)] interface 
2cd90 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
2cda0 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
2cdb0 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63  alue of the func
2cdc0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
2cdd0 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
2cde0 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20  rror code E..** 
2cdf0 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72 72           The err
2ce00 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
2ce10 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
2ce20 0a 2a 2a 20 7b 46 31 36 34 32 37 7d 20 54 68 65  .** {F16427} The
2ce30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2ce40 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65 72  _int(C,V)] inter
2ce50 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2ce60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2ce70 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2ce80 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
2ce90 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  e 32-bit integer
2cea0 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20   value V..**.** 
2ceb0 7b 46 31 36 34 33 30 7d 20 54 68 65 20 5b 73 71  {F16430} The [sq
2cec0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2ced0 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  64(C,V)] interfa
2cee0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
2cef0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2cf00 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
2cf10 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
2cf20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76  64-bit integer v
2cf30 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  alue V..**.** {F
2cf40 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c 69  16433} The [sqli
2cf50 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
2cf60 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
2cf70 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2cf80 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2cf90 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2cfa0 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
2cfb0 2a 2a 20 7b 46 31 36 34 33 36 7d 20 54 68 65 20  ** {F16436} The 
2cfc0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2cfd0 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  text(C,V,N,D)] i
2cfe0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2cff0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d000 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2d010 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2d020 65 20 74 68 65 20 55 54 46 38 20 73 74 72 69 6e  e the UTF8 strin
2d030 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20  g.**          V 
2d040 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2d050 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67  zero if N is neg
2d060 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
2d070 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e    or the first N
2d080 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e   bytes of V if N
2d090 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2d0a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 39 7d  ..**.** {F16439}
2d0b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2d0c0 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
2d0d0 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
2d0e0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
2d0f0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
2d100 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2d110 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46   C to be the UTF
2d120 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2d130 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
2d140 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20   string V up to 
2d150 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69  the first zero i
2d160 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  f N is.**       
2d170 20 20 20 6e 65 67 61 74 69 76 65 20 6f 72 20 74     negative or t
2d180 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
2d190 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   of V if N is no
2d1a0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
2d1b0 2a 20 7b 46 31 36 34 34 32 7d 20 54 68 65 20 5b  * {F16442} The [
2d1c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d1d0 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
2d1e0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2d1f0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2d200 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2d210 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2d220 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20 62  o be the UTF16 b
2d230 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  ig-endian.**    
2d240 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75        string V u
2d250 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
2d260 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20  ero if N is.**  
2d270 20 20 20 20 20 20 20 20 69 73 20 6e 65 67 61 74          is negat
2d280 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73 74  ive or the first
2d290 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69 66   N bytes or V if
2d2a0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
2d2b0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34  ve..**.** {F1644
2d2c0 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
2d2d0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2d2e0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
2d2f0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
2d300 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2d310 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
2d320 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
2d330 20 55 54 46 31 36 20 6c 69 74 74 6c 65 2d 65 6e   UTF16 little-en
2d340 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
2d350 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20   string V up to 
2d360 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69  the first zero i
2d370 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  f N is.**       
2d380 20 20 20 6e 65 67 61 74 69 76 65 20 6f 72 20 74     negative or t
2d390 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
2d3a0 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   of V if N is no
2d3b0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
2d3c0 2a 20 7b 46 31 36 34 34 38 7d 20 54 68 65 20 5b  * {F16448} The [
2d3d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2d3e0 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65 72  alue(C,V)] inter
2d3f0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2d400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2d410 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2d420 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 5b 75  ction C to be [u
2d430 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2d440 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20  e3_value].**    
2d450 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a        object V..
2d460 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20 54  **.** {F16451} T
2d470 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2d480 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29  lt_zeroblob(C,N)
2d490 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2d4a0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2d4b0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2d4c0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2d4d0 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 62  o be an N-byte b
2d4e0 6c 6f 62 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73  lob of all zeros
2d4f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 34 7d  ..**.** {F16454}
2d500 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2d510 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e  sult_error()] an
2d520 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
2d530 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20  t_error16()].** 
2d540 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
2d550 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  ces make a copy 
2d560 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d  of their error m
2d570 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 62  essage strings b
2d580 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  efore.**        
2d590 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a    returning..**.
2d5a0 2a 2a 20 7b 46 31 36 34 35 37 7d 20 49 66 20 74  ** {F16457} If t
2d5b0 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
2d5c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2d5d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2d5e0 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
2d5f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2d600 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
2d610 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
2d620 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2d630 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
2d640 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2d650 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2d660 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
2d670 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2d680 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2d690 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
2d6a0 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51  the constant [SQ
2d6b0 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20  LITE_STATIC].** 
2d6c0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f           then no
2d6d0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65   destructor is e
2d6e0 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  ver called on th
2d6f0 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20  e pointer V and 
2d700 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20  SQLite.**       
2d710 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74 20     assumes that 
2d720 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a  V is immutable..
2d730 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 30 7d 20 49  **.** {F16460} I
2d740 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
2d750 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
2d760 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d770 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
2d780 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2d790 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2d7a0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
2d7b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2d7c0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
2d7d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2d7e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2d7f0 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
2d800 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2d810 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d820 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
2d830 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a  is the constant.
2d840 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2d850 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74  ITE_TRANSIENT] t
2d860 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63  hen the interfac
2d870 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  es makes a copy 
2d880 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
2d890 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20     content of V 
2d8a0 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65 20  and retains the 
2d8b0 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  copy..**.** {F16
2d8c0 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64 65  463} If the D de
2d8d0 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
2d8e0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
2d8f0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
2d900 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
2d910 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
2d920 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
2d930 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
2d940 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
2d950 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2d960 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d970 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
2d980 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
2d990 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2d9a0 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
2d9b0 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61  N,D)] is some va
2d9c0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
2d9d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
2d9e0 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
2d9f0 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51  _STATIC] and [SQ
2da00 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
2da10 74 68 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20  then .**        
2da20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e    SQLite will in
2da30 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
2da40 74 6f 72 20 44 20 77 69 74 68 20 56 20 61 73 20  tor D with V as 
2da50 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  its only argumen
2da60 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  t.**          wh
2da70 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
2da80 65 64 20 77 69 74 68 20 74 68 65 20 56 20 76 61  ed with the V va
2da90 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  lue..*/.void sql
2daa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2dab0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2dac0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2dad0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2dae0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2daf0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
2db00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2db10 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
2db20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2db30 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
2db40 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
2db50 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
2db60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2db70 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
2db80 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2db90 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
2dba0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2dbb0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
2dbc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2dbd0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2dbe0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
2dbf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2dc00 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2dc10 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
2dc20 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2dc30 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
2dc40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2dc50 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2dc60 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
2dc70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2dc80 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
2dc90 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
2dca0 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
2dcb0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
2dcc0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2dcd0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2dce0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
2dcf0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2dd00 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
2dd10 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2dd20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2dd30 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
2dd40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2dd50 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2dd60 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2dd70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2dd80 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
2dd90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2dda0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2ddb0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2ddc0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2ddd0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
2dde0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2ddf0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2de00 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2de10 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2de20 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
2de30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
2de40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
2de50 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2de60 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
2de70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2de80 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
2de90 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
2dea0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
2deb0 65 6e 63 65 73 20 7b 46 31 36 36 30 30 7d 0a 2a  ences {F16600}.*
2dec0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2ded0 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
2dee0 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69   add new collati
2def0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20  on sequences to 
2df00 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a  the.** [sqlite3*
2df10 5d 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69  ] handle specifi
2df20 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
2df30 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a  argument. .**.**
2df40 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
2df50 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   new collation s
2df60 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69  equence is speci
2df70 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20  fied as a UTF-8 
2df80 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
2df90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2dfa0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
2dfb0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2dfc0 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
2dfd0 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
2dfe0 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  g for sqlite3_cr
2dff0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2e000 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73  (). In all cases
2e010 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20  .** the name is 
2e020 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
2e030 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2e040 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
2e050 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2e060 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74   may be one of t
2e070 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
2e080 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
2e090 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20  SQLITE_UTF16LE] 
2e0a0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2e0b0 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  BE], indicating 
2e0c0 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75  that the user-su
2e0d0 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e  pplied.** routin
2e0e0 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20  e expects to be 
2e0f0 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20  passed pointers 
2e100 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64  to strings encod
2e110 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a  ed using UTF-8,.
2e120 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
2e130 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31  -endian or UTF-1
2e140 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73  6 big-endian res
2e150 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a  pectively. The.*
2e160 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
2e170 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b   might also be [
2e180 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2e190 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74  GNED] to indicat
2e1a0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f  e that.** the ro
2e1b0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
2e1c0 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
2e1d0 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
2e1e0 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 31  rings.** of UTF1
2e1f0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
2e200 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68  byte order of th
2e210 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
2e220 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
2e230 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
2e240 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
2e250 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2e260 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
2e270 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73  ument.  If it is
2e280 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
2e290 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
2e2a0 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
2e2b0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
2e2c0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
2e2d0 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
2e2e0 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74  more)..** Each t
2e2f0 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
2e300 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
2e310 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
2e320 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65  ked, it is passe
2e330 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
2e340 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a  void* passed as.
2e350 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  ** the fourth ar
2e360 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2e370 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2e380 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  on() or.** sqlit
2e390 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e3a0 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66  ion16() as its f
2e3b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
2e3c0 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  **.** The remain
2e3d0 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
2e3e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2e3f0 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e  -supplied routin
2e400 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67  e are two string
2e410 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65  s,.** each repre
2e420 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e  sented by a (len
2e430 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20  gth, data) pair 
2e440 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74  and encoded in t
2e450 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74  he encoding.** t
2e460 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61  hat was passed a
2e470 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
2e480 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f  ment when the co
2e490 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2e4a0 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72   was.** register
2e4b0 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65 20 61 70  ed. {END} The ap
2e4c0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2e4d0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74  d collation rout
2e4e0 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ine should.** re
2e4f0 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a  turn negative, z
2e500 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20  ero or positive 
2e510 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  if.** the first 
2e520 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
2e530 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f  han, equal to, o
2e540 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
2e550 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72  he second.** str
2e560 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e  ing. i.e. (STRIN
2e570 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a  G1 - STRING2)..*
2e580 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2e590 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2e5a0 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
2e5b0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2e5c0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
2e5d0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74  except that it t
2e5e0 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72  akes an extra ar
2e5f0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2e600 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  a destructor for
2e610 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  .** the collatio
2e620 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74  n.  The destruct
2e630 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65  or is called whe
2e640 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
2e650 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20  is.** destroyed 
2e660 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20  and is passed a 
2e670 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72  copy of the four
2e680 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69  th parameter voi
2e690 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66  d* pointer.** of
2e6a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   the sqlite3_cre
2e6b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2e6c0 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e  ()..** Collation
2e6d0 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20  s are destroyed 
2e6e0 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65  when.** they are
2e6f0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
2e700 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68  ater calls to th
2e710 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
2e720 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  tion functions.*
2e730 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 73  * or when the [s
2e740 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73  qlite3*] databas
2e750 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73  e handle is clos
2e760 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2e770 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
2e780 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2e790 0a 2a 2a 20 7b 46 31 36 36 30 33 7d 20 41 20 73  .** {F16603} A s
2e7a0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2e7b0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
2e7c0 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
2e7d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
2e7e0 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74  ,X,E,P,F,D)] int
2e7f0 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  erface.**       
2e800 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e     registers fun
2e810 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63  ction F as the c
2e820 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
2e830 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20  on used to.**   
2e840 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74         implement
2e850 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20   collation X on 
2e860 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2e870 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20  tion] B for.**  
2e880 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
2e890 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e  s having encodin
2e8a0 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  g E..**.** {F166
2e8b0 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72  04} SQLite under
2e8c0 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61 72  stands the X par
2e8d0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
2e8e0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2e8f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2e900 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
2e910 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   as a zero-termi
2e920 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
2e930 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69    UTF-8 string i
2e940 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73 20  n which case is 
2e950 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49  ignored for ASCI
2e960 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64  I characters and
2e970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2e980 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20  significant for 
2e990 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63  non-ASCII charac
2e9a0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ters..**.** {F16
2e9b0 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65 20  606} Successive 
2e9c0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2e9d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2e9e0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
2e9f0 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D)].**          
2ea00 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61  with the same va
2ea10 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61  lues for B, X, a
2ea20 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70  nd E, override p
2ea30 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20  rior values.**  
2ea40 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c          of P, F,
2ea50 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46   and D..**.** {F
2ea60 31 36 36 30 39 7d 20 54 68 65 20 64 65 73 74 72  16609} The destr
2ea70 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69  uctor D in [sqli
2ea80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2ea90 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
2eaa0 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,D)].**        
2eab0 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68    is not NULL th
2eac0 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20  en it is called 
2ead0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
2eae0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  when the.**     
2eaf0 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66       collating f
2eb00 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
2eb10 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  ed by SQLite..**
2eb20 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 20 41 20 63  .** {F16612} A c
2eb30 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2eb40 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65  n is dropped whe
2eb50 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61 64  n it is overload
2eb60 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31  ed..**.** {F1661
2eb70 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  5} A collating f
2eb80 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
2eb90 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ed when the data
2eba0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
2ebb0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63  **          is c
2ebc0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
2ebd0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
2ebe0 2a 0a 2a 2a 20 7b 46 31 36 36 31 38 7d 20 54 68  *.** {F16618} Th
2ebf0 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b  e pointer P in [
2ec00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2ec10 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
2ec20 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20  E,P,F,D)].**    
2ec30 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64 20        is passed 
2ec40 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
2ec50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
2ec60 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e  o the comparison
2ec70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
2ec80 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20  ction F for all 
2ec90 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2eca0 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a  ations of F..**.
2ecb0 2a 2a 20 7b 46 31 36 36 32 31 7d 20 41 20 63 61  ** {F16621} A ca
2ecc0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2ecd0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2ece0 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65  B,X,E,P,F)] is e
2ecf0 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  xactly.**       
2ed00 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 61     the same as a
2ed10 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2ed20 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2ed30 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a  on_v2()] with.**
2ed40 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
2ed50 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  me parameters an
2ed60 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75 63  d a NULL destruc
2ed70 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  tor..**.** {F166
2ed80 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20  24} Following a 
2ed90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2eda0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
2edb0 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20  ,E,P,F,D)],.**  
2edc0 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 75          SQLite u
2edd0 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73  ses the comparis
2ede0 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f  on function F fo
2edf0 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61  r all text compa
2ee00 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  rison.**        
2ee10 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20    operations on 
2ee20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ee30 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20  tion] B on text 
2ee40 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20  values that.**  
2ee50 20 20 20 20 20 20 20 20 75 73 65 20 74 68 65 20          use the 
2ee60 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
2ee70 63 65 20 6e 61 6d 65 20 58 2e 0a 2a 2a 0a 2a 2a  ce name X..**.**
2ee80 20 7b 46 31 36 36 32 37 7d 20 54 68 65 20 5b 73   {F16627} The [s
2ee90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2eea0 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c  llation16(B,X,E,
2eeb0 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20  P,F)] works the 
2eec0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
2eed0 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   as [sqlite3_cre
2eee0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
2eef0 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74  X,E,P,F)] except
2ef00 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
2ef10 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20        collation 
2ef20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73  name X is unders
2ef30 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69  tood as UTF-16 i
2ef40 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
2ef50 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
2ef60 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
2ef70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 33 30 7d  ..**.** {F16630}
2ef80 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63   When multiple c
2ef90 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
2efa0 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
2efb0 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a  e for the same.*
2efc0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
2efd0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53  ting sequence, S
2efe0 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68  QLite chooses th
2eff0 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74  e one whose text
2f000 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20   encoding.**    
2f010 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20 74        requires t
2f020 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
2f030 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72  of conversion fr
2f040 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  om the default.*
2f050 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
2f060 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
2f070 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74  database..*/.int
2f080 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f090 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
2f0a0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
2f0b0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
2f0c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2f0d0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
2f0e0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
2f0f0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
2f100 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
2f110 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2f120 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2f130 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
2f140 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2f150 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
2f160 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2f170 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2f180 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2f190 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2f1a0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
2f1b0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2f1c0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2f1d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2f1e0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
2f1f0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
2f200 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
2f210 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
2f220 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
2f230 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2f240 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2f250 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
2f260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2f270 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
2f280 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 36 37 30  Callbacks {F1670
2f290 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  0}.**.** To avoi
2f2a0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
2f2b0 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
2f2c0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
2f2d0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
2f2e0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
2f2f0 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
2f300 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
2f310 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
2f320 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2f330 20 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61   handle to be ca
2f340 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  lled whenever an
2f350 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
2f360 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
2f370 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  .** required..**
2f380 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74  .** If the funct
2f390 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
2f3a0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
2f3b0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2f3c0 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
2f3d0 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
2f3e0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
2f3f0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2f400 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
2f410 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
2f420 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 46 31 36  d in UTF-8. {F16
2f430 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f  703} If sqlite3_
2f440 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2f450 31 36 28 29 20 69 73 20 75 73 65 64 2c 20 74 68  16() is used, th
2f460 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70  e names.** are p
2f470 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
2f480 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
2f490 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20 41 20  e byte order. A 
2f4a0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a  call to either.*
2f4b0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  * function repla
2f4c0 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67  ces any existing
2f4d0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
2f4e0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
2f4f0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
2f500 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2f510 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
2f520 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
2f530 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
2f540 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2f550 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
2f560 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2f570 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
2f580 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2f590 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
2f5a0 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 20  ase.** handle.  
2f5b0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2f5c0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2f5d0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
2f5e0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2f5f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2f600 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
2f610 20 74 68 65 20 6d 6f 73 74 0a 2a 2a 20 64 65 73   the most.** des
2f620 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
2f630 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
2f640 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
2f650 65 71 75 69 72 65 64 2e 0a 2a 2a 20 54 68 65 20  equired..** The 
2f660 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2f670 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
2f680 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
2f690 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2f6a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ce..**.** The ca
2f6b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2f6c0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
2f6d0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
2f6e0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
2f6f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2f700 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
2f710 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2f720 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
2f730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2f740 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2f750 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
2f760 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
2f770 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  702} A successfu
2f780 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2f790 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2f7a0 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20  ded(D,P,F)].**  
2f7b0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
2f7c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2f7d0 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63  eded16(D,P,F)] c
2f7e0 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  auses.**        
2f7f0 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20    the [database 
2f800 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f  connection] D to
2f810 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b   invoke callback
2f820 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a   F with first.**
2f830 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
2f840 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20 69  ter P whenever i
2f850 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72  t needs a compar
2f860 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ison function fo
2f870 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r a.**          
2f880 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
2f890 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  ce that it does 
2f8a0 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a  not know about..
2f8b0 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 34 7d 20 45  **.** {F16704} E
2f8c0 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20 63  ach successful c
2f8d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2f8e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2f8f0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
2f900 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c     [sqlite3_coll
2f910 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2f920 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
2f930 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65  callback registe
2f940 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
2f950 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2f960 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f970 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  ] by prior calls
2f980 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20   to either.**   
2f990 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
2f9a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 36 7d  ..**.** {F16706}
2f9b0 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
2f9c0 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61   requested colla
2f9d0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ting function pa
2f9e0 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ssed in the.**  
2f9f0 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72 61          4th para
2fa00 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
2fa10 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d  lback is in UTF-
2fa20 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  8 if the callbac
2fa30 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61  k.**          wa
2fa40 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
2fa50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
2fa60 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
2fa70 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
2fa80 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74  is in UTF-16 nat
2fa90 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
2faa0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  f the callback w
2fab0 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  as.**          r
2fac0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2fad0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2fae0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
2faf0 2a 2a 0a 2a 2a 20 0a 2a 2f 0a 69 6e 74 20 73 71  **.** .*/.int sq
2fb00 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2fb10 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
2fb20 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
2fb30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
2fb40 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
2fb50 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
2fb60 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2fb70 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2fb80 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
2fb90 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
2fba0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2fbb0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
2fbc0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2fbd0 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
2fbe0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
2fbf0 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
2fc00 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
2fc10 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
2fc20 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
2fc30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
2fc40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2fc50 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2fc60 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2fc70 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2fc80 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2fc90 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2fca0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2fcb0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2fcc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fcd0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2fce0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2fcf0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2fd00 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2fd10 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2fd20 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2fd30 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2fd40 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2fd50 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2fd60 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2fd70 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2fd80 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2fd90 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2fda0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2fdb0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2fdc0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2fdd0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2fde0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2fdf0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2fe00 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2fe10 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2fe20 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2fe30 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
2fe40 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2fe50 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2fe60 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2fe70 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2fe80 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2fe90 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2fea0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
2feb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fec0 20 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74    Suspend Execut
2fed0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
2fee0 54 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a 2a 2a  Time {F10530}.**
2fef0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ff00 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
2ff10 0a 2a 2a 20 63 61 75 73 65 73 20 74 68 65 20 63  .** causes the c
2ff20 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
2ff30 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
2ff40 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
2ff50 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
2ff60 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
2ff70 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
2ff80 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
2ff90 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
2ffa0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
2ffb0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
2ffc0 75 65 73 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d  uests with .** m
2ffd0 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
2ffe0 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
2fff0 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
30000 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 20  e rounded up to 
30010 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
30020 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
30030 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
30040 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
30050 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73 74  ally .** request
30060 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
30070 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
30080 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
30090 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
300a0 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
300b0 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
300c0 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
300d0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
300e0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
300f0 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  object..**.** IN
30100 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
30110 7b 46 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71  {F10533} The [sq
30120 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20  lite3_sleep(M)] 
30130 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65  interface invoke
30140 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20  s the xSleep.** 
30150 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20           method 
30160 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
30170 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d  sqlite3_vfs|VFS]
30180 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
30190 20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e 64           suspend
301a0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
301b0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
301c0 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a   for at least.**
301d0 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c            M mill
301e0 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20  iseconds..**.** 
301f0 7b 46 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71  {F10536} The [sq
30200 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20  lite3_sleep(M)] 
30210 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30220 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
30230 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c  **          mill
30240 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
30250 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65  p actually reque
30260 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72  sted of the oper
30270 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ating.**        
30280 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20    system, which 
30290 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
302a0 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74  than the paramet
302b0 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  er M..*/.int sql
302c0 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
302d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
302e0 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  :  Name Of The F
302f0 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
30300 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 46  mporary Files {F
30310 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20  10310}.**.** If 
30320 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
30330 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
30340 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
30350 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
30360 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
30370 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
30380 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
30390 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
303a0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
303b0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61  Lite will be pla
303c0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
303d0 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20  ctory.  If this 
303e0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e  variable.** is N
303f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
30400 6e 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20  n SQLite does a 
30410 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
30420 70 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72  propriate tempor
30430 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65  ary.** file dire
30440 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
30450 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d  is not safe to m
30460 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
30470 62 6c 65 20 6f 6e 63 65 20 61 20 64 61 74 61 62  ble once a datab
30480 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
30490 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65  * has been opene
304a0 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64  d.  It is intend
304b0 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
304c0 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
304d0 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
304e0 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
304f0 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
30500 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
30510 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
30520 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
30530 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63  l and remain unc
30540 68 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65  hanged thereafte
30550 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  r..*/.SQLITE_EXT
30560 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
30570 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
30580 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30590 46 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65 20  F:  Test To See 
305a0 49 66 20 54 68 65 20 44 61 74 61 62 61 73 65 20  If The Database 
305b0 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69  Is In Auto-Commi
305c0 74 20 4d 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a  t Mode {F12930}.
305d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
305e0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
305f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
30600 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
30610 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
30620 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
30630 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
30640 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
30650 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
30660 73 70 65 63 74 69 76 65 6c 79 2e 20 20 20 41 75  spectively.   Au
30670 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
30680 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c   on.** by defaul
30690 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  t.  Autocommit m
306a0 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
306b0 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
306c0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63  tement..** Autoc
306d0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
306e0 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
306f0 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
30700 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
30710 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
30720 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
30730 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
30740 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
30750 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
30760 69 6f 6e 73 20 28 65 72 72 6f 72 73 20 69 6e 63  ions (errors inc
30770 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
30780 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
30790 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54  ERR], .** [SQLIT
307a0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
307b0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
307c0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
307d0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
307e0 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
307f0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
30800 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
30810 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
30820 20 66 69 6e 64 20 6f 75 74 20 69 66 20 53 51 4c   find out if SQL
30830 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
30840 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68  y rolled back th
30850 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66  e transaction af
30860 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  ter.** an error 
30870 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66  is to use this f
30880 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
30890 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
308a0 20 7b 46 31 32 39 33 31 7d 20 54 68 65 20 5b 73   {F12931} The [s
308b0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
308c0 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72 66  ommit(D)] interf
308d0 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ace returns non-
308e0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20  zero or.**      
308f0 20 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65 20      zero if the 
30900 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30910 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69 73  tion] D is or is
30920 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
30930 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  it.**          m
30940 6f 64 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ode, respectivel
30950 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32  y..**.** {F12932
30960 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
30970 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
30980 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33  lt..**.** {F1293
30990 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  3} Autocommit mo
309a0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
309b0 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b  y a successful [
309c0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
309d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d  ..**.** {F12934}
309e0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
309f0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61   is enabled by a
30a00 20 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d   successful [COM
30a10 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
30a20 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  K].**          s
30a30 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a  tatement..** .**
30a40 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
30a50 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d  .***.** {U12936}
30a60 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
30a70 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
30a80 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
30a90 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
30aa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
30ab0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
30ac0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
30ad0 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
30ae0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
30af0 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65           is unde
30b00 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
30b10 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
30b20 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
30b30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30b40 20 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62    Find The Datab
30b50 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
30b60 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
30b70 6e 74 20 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a  nt {F13120}.**.*
30b80 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
30b90 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
30ba0 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
30bb0 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61   [sqlite3*] data
30bc0 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 77  base handle to w
30bd0 68 69 63 68 20 61 0a 2a 2a 20 5b 70 72 65 70 61  hich a.** [prepa
30be0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
30bf0 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 64  elongs..** The d
30c00 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72  atabase handle r
30c10 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
30c20 65 33 5f 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20  e3_db_handle.** 
30c30 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  is the same data
30c40 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74  base handle that
30c50 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 72 73   was.** the firs
30c60 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
30c70 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
30c80 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
30c90 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74  variants.** that
30ca0 20 77 61 73 20 75 73 65 64 20 74 6f 20 63 72 65   was used to cre
30cb0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
30cc0 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
30cd0 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  lace..**.** INVA
30ce0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
30cf0 31 33 31 32 33 7d 20 54 68 65 20 5b 73 71 6c 69  13123} The [sqli
30d00 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29  te3_db_handle(S)
30d10 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
30d20 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
30d30 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
30d40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30d50 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ction] associate
30d60 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  d with.**       
30d70 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
30d80 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71  tement] S..*/.sq
30d90 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
30da0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
30db0 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _stmt*);.../*.**
30dc0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
30dd0 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
30de0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
30df0 62 61 63 6b 73 20 7b 46 31 32 39 35 30 7d 0a 2a  backs {F12950}.*
30e00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30e10 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
30e20 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
30e30 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
30e40 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30e50 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
30e60 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
30e70 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
30e80 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
30e90 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
30ea0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
30eb0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
30ec0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
30ed0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30ee0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
30ef0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30f00 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
30f10 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
30f20 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
30f30 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30f40 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
30f50 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
30f60 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
30f70 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
30f80 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
30f90 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
30fa0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
30fb0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
30fc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30fd0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
30fe0 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67 75  ** The pArg argu
30ff0 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
31000 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65  hrough.** to the
31010 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74   callback.  If t
31020 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
31030 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
31040 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e  ction .** return
31050 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
31060 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
31070 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
31080 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
31090 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
310a0 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
310b0 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
310c0 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65  ts.** pArg value
310d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
310e0 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
310f0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
31100 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e   Registering a N
31110 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
31120 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
31130 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  ck..**.** For th
31140 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
31150 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61  is API, a transa
31160 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f  ction is said to
31170 20 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72   have been .** r
31180 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
31190 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
311a0 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
311b0 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
311c0 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
311d0 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
311e0 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
311f0 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a  back to occur..*
31200 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  * The rollback c
31210 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
31220 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
31230 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
31240 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
31250 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
31260 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
31270 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
31280 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  d..** The rollba
31290 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
312a0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
312b0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
312c0 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  * rolled back be
312d0 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63  cause a commit c
312e0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64  allback returned
312f0 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74   non-zero..** <t
31300 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68  odo> Check on th
31310 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  is </todo>.**.**
31320 20 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72   These are exper
31330 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63  imental interfac
31340 65 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65  es and are subje
31350 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2a  ct to change..**
31360 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
31370 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54  **.** {F12951} T
31380 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
31390 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
313a0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
313b0 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ers the.**      
313c0 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e      callback fun
313d0 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
313e0 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
313f0 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
31400 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61  *          a tra
31410 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73  nsaction commits
31420 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
31430 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
31440 2a 2a 20 7b 46 31 32 39 35 32 7d 20 54 68 65 20  ** {F12952} The 
31450 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
31460 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
31470 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
31480 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20  he P.**         
31490 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
314a0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
314b0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 0a   with the same .
314c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
314d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
314e0 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f   ] D , or NULL o
314f0 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  n the first call
31500 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
31510 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 64   a particular [d
31520 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31530 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
31540 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c 6c 20  2953} Each call 
31550 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  to [sqlite3_comm
31560 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77  it_hook()] overw
31570 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61  rites the callba
31580 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ck.**          r
31590 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69  egistered by pri
315a0 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20  or calls..**.** 
315b0 7b 46 31 32 39 35 34 7d 20 49 66 20 74 68 65 20  {F12954} If the 
315c0 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  F argument to [s
315d0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
315e0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55  ok(D,F,P)] is NU
315f0 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
31600 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
31610 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ook callback is 
31620 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20  canceled and no 
31630 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
31640 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20       is invoked 
31650 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69  when a transacti
31660 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a  on commits..**.*
31670 2a 20 7b 46 31 32 39 35 35 7d 20 49 66 20 74 68  * {F12955} If th
31680 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63  e commit callbac
31690 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
316a0 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ro then the comm
316b0 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  it is.**        
316c0 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f    converted into
316d0 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
316e0 2a 2a 20 7b 46 31 32 39 36 31 7d 20 54 68 65 20  ** {F12961} The 
316f0 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
31700 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
31710 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
31720 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rs the.**       
31730 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63     callback func
31740 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
31750 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
31760 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
31770 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e            a tran
31780 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61  saction rolls ba
31790 63 6b 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ck on [database 
317a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
317b0 2a 0a 2a 2a 20 7b 46 31 32 39 36 32 7d 20 54 68  *.** {F12962} Th
317c0 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  e [sqlite3_rollb
317d0 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ack_hook(D,F,P)]
317e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
317f0 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20  ns the P.**     
31800 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72       argument fr
31810 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
31820 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61  call with the sa
31830 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  me .**          
31840 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
31850 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55  tion ] D , or NU
31860 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  LL on the first 
31870 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  call.**         
31880 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
31890 72 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  r [database conn
318a0 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
318b0 20 7b 46 31 32 39 36 33 7d 20 45 61 63 68 20 63   {F12963} Each c
318c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
318d0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d  rollback_hook()]
318e0 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20   overwrites the 
318f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
31900 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
31910 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a  by prior calls..
31920 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 34 7d 20 49  **.** {F12964} I
31930 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74  f the F argument
31940 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c   to [sqlite3_rol
31950 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50  lback_hook(D,F,P
31960 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
31970 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
31980 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61  rollback hook ca
31990 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c  llback is cancel
319a0 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61  ed and no callba
319b0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ck.**          i
319c0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
319d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c   transaction rol
319e0 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64  ls back..*/.void
319f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   *sqlite3_commit
31a00 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
31a10 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
31a20 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  oid*);.void *sql
31a30 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
31a40 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ok(sqlite3*, voi
31a50 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f  d(*)(void *), vo
31a60 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
31a70 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e  I3REF: Data Chan
31a80 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ge Notification 
31a90 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 37  Callbacks {F1297
31aa0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
31ab0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
31ac0 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
31ad0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
31ae0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
31af0 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
31b00 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74  connection ident
31b10 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
31b20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
31b30 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
31b40 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
31b50 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
31b60 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
31b70 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
31b80 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
31b90 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e  call to this fun
31ba0 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 61  ction for the sa
31bb0 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  me .** database 
31bc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
31bd0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
31be0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
31bf0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
31c00 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
31c10 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20   to invoke when 
31c20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64  a .** row is upd
31c30 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
31c40 72 20 64 65 6c 65 74 65 64 2e 20 0a 2a 2a 20 54  r deleted. .** T
31c50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
31c60 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
31c70 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f  k is.** a copy o
31c80 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
31c90 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
31ca0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
31cb0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c  * The second cal
31cc0 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75 6d 65  lback .** argume
31cd0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
31ce0 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
31cf0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72  QLITE_DELETE] or
31d00 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
31d10 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f  ,.** depending o
31d20 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
31d30 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
31d40 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69  callback to be i
31d50 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74  nvoked..** The t
31d60 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75  hird and .** fou
31d70 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
31d80 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
31d90 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
31da0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  o the database a
31db0 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d  nd .** table nam
31dc0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
31dd0 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
31de0 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  * The final call
31df0 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
31e00 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20  s .** the rowid 
31e10 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49  of the row..** I
31e20 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
31e30 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
31e40 20 74 68 65 20 72 6f 77 69 64 20 61 66 74 65 72   the rowid after
31e50 20 0a 2a 2a 20 74 68 65 20 75 70 64 61 74 65 20   .** the update 
31e60 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
31e70 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  ** The update ho
31e80 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
31e90 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
31ea0 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
31eb0 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
31ec0 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
31ed0 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
31ee0 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  uence)..**.** If
31ef0 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f   another functio
31f00 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79  n was previously
31f10 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73   registered, its
31f20 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69   pArg value.** i
31f30 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
31f40 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72  erwise NULL is r
31f50 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
31f60 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
31f70 20 7b 46 31 32 39 37 31 7d 20 54 68 65 20 5b 73   {F12971} The [s
31f80 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
31f90 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
31fa0 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c  face causes call
31fb0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
31fc0 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62   function F to b
31fd0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66  e invoked with f
31fe0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 50  irst parameter P
31ff0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20   whenever.**    
32000 20 20 20 20 20 20 61 20 74 61 62 6c 65 20 72 6f        a table ro
32010 77 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20 69  w is modified, i
32020 6e 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c 65  nserted, or dele
32030 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ted on.**       
32040 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
32050 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
32060 2a 20 7b 46 31 32 39 37 33 7d 20 54 68 65 20 5b  * {F12973} The [
32070 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
32080 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
32090 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
320a0 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20  e value.**      
320b0 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68 65      of P for the
320c0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f   previous call o
320d0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
320e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
320f0 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   D,.**          
32100 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65 20  or NULL for the 
32110 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  first call..**.*
32120 2a 20 7b 46 31 32 39 37 35 7d 20 49 66 20 74 68  * {F12975} If th
32130 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61  e update hook ca
32140 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c  llback F in [sql
32150 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
32160 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20  (D,F,P)].**     
32170 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68 65       is NULL the
32180 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65 20  n the no update 
32190 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d 61  callbacks are ma
321a0 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37  de..**.** {F1297
321b0 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  7} Each call to 
321c0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
321d0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 65  hook(D,F,P)] ove
321e0 72 72 69 64 65 73 20 70 72 69 6f 72 20 63 61 6c  rrides prior cal
321f0 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ls.**          t
32200 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65 72  o the same inter
32210 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d 65  face on the same
32220 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32230 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
32240 7b 46 31 32 39 37 39 7d 20 54 68 65 20 75 70 64  {F12979} The upd
32250 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  ate hook callbac
32260 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
32270 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
32280 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20 20  ystem.**        
32290 20 20 74 61 62 6c 65 73 20 73 75 63 68 20 61 73    tables such as
322a0 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
322b0 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
322c0 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64 2e  ce are modified.
322d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20  .**.** {F12981} 
322e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
322f0 65 74 65 72 20 74 6f 20 74 68 65 20 75 70 64 61  eter to the upda
32300 74 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20  te callback .** 
32310 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65 20           is one 
32320 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
32330 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
32340 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  TE] or [SQLITE_U
32350 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20  PDATE],.**      
32360 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e      depending on
32370 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
32380 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
32390 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e  allback to be in
323a0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  voked..**.** {F1
323b0 32 39 38 33 7d 20 54 68 65 20 74 68 69 72 64 20  2983} The third 
323c0 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
323d0 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
323e0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
323f0 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  nters.**        
32400 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e    to zero-termin
32410 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
32420 67 73 20 77 68 69 63 68 20 61 72 65 20 74 68 65  gs which are the
32430 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
32440 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
32450 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68 61  se and table tha
32460 74 20 69 73 20 62 65 69 6e 67 20 75 70 64 61 74  t is being updat
32470 65 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39 38 35 7d  ed...** {F12985}
32480 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62   The final callb
32490 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
324a0 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
324b0 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20  e row after.**  
324c0 20 20 20 20 20 20 20 20 74 68 65 20 63 68 61 6e          the chan
324d0 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f  ge occurs..*/.vo
324e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
324f0 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
32500 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
32510 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
32520 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
32530 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
32540 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
32550 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32560 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  :  Enable Or Dis
32570 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65  able Shared Page
32580 72 20 43 61 63 68 65 20 7b 46 31 30 33 33 30 7d  r Cache {F10330}
32590 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
325a0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
325b0 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
325c0 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
325d0 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
325e0 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
325f0 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
32600 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74  connections to t
32610 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
32620 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20  ..** Sharing is 
32630 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
32640 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20  rgument is true 
32650 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20  and disabled if 
32660 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  the argument.** 
32670 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20  is false..**.** 
32680 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73  Cache sharing is
32690 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73   enabled and dis
326a0 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20  abled.** for an 
326b0 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20  entire process. 
326c0 7b 45 4e 44 7d 20 54 68 69 73 20 69 73 20 61 20  {END} This is a 
326d0 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c  change as of SQL
326e0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
326f0 30 2e 0a 2a 2a 20 49 6e 20 70 72 69 6f 72 20 76  0..** In prior v
32700 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
32710 65 2c 20 73 68 61 72 69 6e 67 20 77 61 73 0a 2a  e, sharing was.*
32720 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  * enabled or dis
32730 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74  abled for each t
32740 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79  hread separately
32750 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68  ..**.** The cach
32760 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
32770 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
32780 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
32790 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
327a0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
327b0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
327c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
327d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
327e0 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
327f0 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
32800 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
32810 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
32820 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
32830 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
32840 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
32850 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  e opened..**.** 
32860 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63  Virtual tables c
32870 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69  annot be used wi
32880 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68  th a shared cach
32890 65 2e 20 20 20 57 68 65 6e 20 73 68 61 72 65 64  e.   When shared
328a0 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
328b0 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74  bled, the [sqlit
328c0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
328d0 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20  ()] API used to 
328e0 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74  register.** virt
328f0 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20  ual tables will 
32900 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e  always return an
32910 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
32920 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
32930 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ns [SQLITE_OK] i
32940 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77  f shared cache w
32950 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72  as.** enabled or
32960 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73   disabled succes
32970 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72  sfully.  An [err
32980 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72  or code].** is r
32990 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
329a0 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20  e..**.** Shared 
329b0 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65  cache is disable
329c0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75  d by default. Bu
329d0 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61  t this might cha
329e0 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  nge in.** future
329f0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
32a00 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ite.  Applicatio
32a10 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f  ns that care abo
32a20 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ut shared.** cac
32a30 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c  he setting shoul
32a40 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69  d set it explici
32a50 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  tly..**.** INVAR
32a60 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46  IANTS:.** .** {F
32a70 31 30 33 33 31 7d 20 41 20 73 75 63 63 65 73 73  10331} A success
32a80 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
32a90 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  f [sqlite3_enabl
32aa0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 42  e_shared_cache(B
32ab0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
32ac0 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64 69  ill enable or di
32ad0 73 61 62 6c 65 20 73 68 61 72 65 64 20 63 61 63  sable shared cac
32ae0 68 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20  he mode for any 
32af0 73 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20  subsequently.** 
32b00 20 20 20 20 20 20 20 20 20 63 72 65 61 74 65 64           created
32b10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32b20 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61  ction] in the sa
32b30 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a  me process..**.*
32b40 2a 20 7b 46 31 30 33 33 36 7d 20 57 68 65 6e 20  * {F10336} When 
32b50 73 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  shared cache is 
32b60 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71  enabled, the [sq
32b70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
32b80 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ule()].**       
32b90 20 20 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c     interface wil
32ba0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
32bb0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  an error..**.** 
32bc0 7b 46 31 30 33 33 37 7d 20 54 68 65 20 5b 73 71  {F10337} The [sq
32bd0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
32be0 72 65 64 5f 63 61 63 68 65 28 42 29 5d 20 69 6e  red_cache(B)] in
32bf0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
32c00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
32c10 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
32c20 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
32c30 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
32c40 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a  successfully..**
32c50 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53 68 61  .** {F10339} Sha
32c60 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
32c70 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
32c80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32c90 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
32ca0 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
32cb0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41 74 74  * CAPI3REF:  Att
32cc0 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
32cd0 70 20 4d 65 6d 6f 72 79 20 7b 46 31 37 33 34 30  p Memory {F17340
32ce0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
32cf0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
32d00 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  ry() interface a
32d10 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 66 72  ttempts to.** fr
32d20 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65  ee N bytes of he
32d30 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
32d40 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
32d50 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 0a 2a  sential memory.*
32d60 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65  * allocations he
32d70 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
32d80 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44  se library. {END
32d90 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 0a 2a  }  Memory used.*
32da0 2a 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62  * to cache datab
32db0 61 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d 70  ase pages to imp
32dc0 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
32dd0 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
32de0 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  f.** non-essenti
32df0 61 6c 20 6d 65 6d 6f 72 79 2e 20 20 53 71 6c 69  al memory.  Sqli
32e00 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
32e10 72 79 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ry() returns.** 
32e20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
32e30 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
32e40 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20  ed, which might 
32e50 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a  be more or less.
32e60 2a 2a 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ** than the amou
32e70 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a  nt requested..**
32e80 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
32e90 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d 20 54  **.** {F17341} T
32ea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  he [sqlite3_rele
32eb0 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69  ase_memory(N)] i
32ec0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
32ed0 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  s to.**         
32ee0 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66   free N bytes of
32ef0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
32f00 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
32f10 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20  -essential.**   
32f20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c         memory al
32f30 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62  locations held b
32f40 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
32f50 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ibrary..**.** {F
32f60 31 36 33 34 32 7d 20 54 68 65 20 5b 73 71 6c 69  16342} The [sqli
32f70 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
32f80 72 79 28 4e 29 5d 20 72 65 74 75 72 6e 73 20 74  ry(N)] returns t
32f90 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20  he number.**    
32fa0 20 20 20 20 20 20 6f 66 20 62 79 74 65 73 20 61        of bytes a
32fb0 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77  ctually freed, w
32fc0 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f  hich might be mo
32fd0 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20  re or less.**   
32fe0 20 20 20 20 20 20 20 74 68 61 6e 20 74 68 65 20         than the 
32ff0 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
33000 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33010 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
33020 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
33030 49 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41  I3REF:  Impose A
33040 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53   Limit On Heap S
33050 69 7a 65 20 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a  ize {F17350}.**.
33060 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
33070 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29  oft_heap_limit()
33080 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 70 6c   interface.** pl
33090 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69  aces a "soft" li
330a0 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e  mit on the amoun
330b0 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  t of heap memory
330c0 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c   that may be all
330d0 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c  ocated.** by SQL
330e0 69 74 65 2e 20 49 66 20 61 6e 20 69 6e 74 65 72  ite. If an inter
330f0 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  nal allocation i
33100 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20  s requested .** 
33110 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65  that would excee
33120 64 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  d the soft heap 
33130 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f  limit, [sqlite3_
33140 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
33150 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  ] is.** invoked 
33160 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
33170 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d  s to free up som
33180 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74  e space before t
33190 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  he allocation.**
331a0 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20   is made..**.** 
331b0 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c  The limit is cal
331c0 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61  led "soft", beca
331d0 75 73 65 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74  use if.** [sqlit
331e0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
331f0 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66  y()] cannot.** f
33200 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d  ree sufficient m
33210 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74  emory to prevent
33220 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20   the limit from 
33230 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a  being exceeded,.
33240 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73  ** the memory is
33250 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61   allocated anywa
33260 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e  y and the curren
33270 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  t operation proc
33280 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65  eeds..**.** A ne
33290 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76  gative or zero v
332a0 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73  alue for N means
332b0 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e   that there is n
332c0 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  o soft heap limi
332d0 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  t and.** [sqlite
332e0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
332f0 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65  ()] will only be
33300 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d   called when mem
33310 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65 64  ory is exhausted
33320 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
33330 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73   value for the s
33340 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
33350 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51  s zero..**.** SQ
33360 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73  Lite makes a bes
33370 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f  t effort to hono
33380 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
33390 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 42 75 74 20  limit.  .** But 
333a0 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  if the soft heap
333b0 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65   limit cannot be
333c0 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74   honored, execut
333d0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  ion will.** cont
333e0 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72  inue without err
333f0 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69  or or notificati
33400 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79  on.  This is why
33410 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a   the limit is .*
33420 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74  * called a "soft
33430 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20  " limit.  It is 
33440 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
33450 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
33460 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
33470 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .0, this routine
33480 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65   only constraine
33490 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  d the memory.** 
334a0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73  allocated by a s
334b0 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74  ingle thread - t
334c0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
334d0 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75  n which this rou
334e0 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42  tine.** runs.  B
334f0 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51  eginning with SQ
33500 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
33510 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61  .0, the soft hea
33520 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70  p limit is.** ap
33530 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72  plied to all thr
33540 65 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20  eads. The value 
33550 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68  specified for th
33560 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
33570 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72  t.** is an upper
33580 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f   bound on the to
33590 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tal memory alloc
335a0 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68  ation for all th
335b0 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72  reads. In.** ver
335c0 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65  sion 3.5.0 there
335d0 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d   is no mechanism
335e0 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68   for limiting th
335f0 65 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72  e heap usage for
33600 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74  .** individual t
33610 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  hreads..**.** IN
33620 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
33630 7b 46 31 36 33 35 31 7d 20 54 68 65 20 5b 73 71  {F16351} The [sq
33640 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
33650 6c 69 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72 66  limit(N)] interf
33660 61 63 65 20 70 6c 61 63 65 73 20 61 20 73 6f 66  ace places a sof
33670 74 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20  t limit.**      
33680 20 20 20 20 6f 66 20 4e 20 62 79 74 65 73 20 6f      of N bytes o
33690 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
336a0 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
336b0 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
336c0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73  d.**          us
336d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
336e0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
336f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74  e3_realloc()] at
33700 20 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20   any point.**   
33710 20 20 20 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a         in time..
33720 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 32 7d 20 49  **.** {F16352} I
33730 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  f a call to [sql
33740 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
33750 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
33760 6f 63 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20  oc()] would.**  
33770 20 20 20 20 20 20 20 20 63 61 75 73 65 20 74 68          cause th
33780 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f  e total amount o
33790 66 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f  f allocated memo
337a0 72 79 20 74 6f 20 65 78 63 65 65 64 20 74 68 65  ry to exceed the
337b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6f 66  .**          sof
337c0 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 74 68  t heap limit, th
337d0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  en [sqlite3_rele
337e0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73  ase_memory()] is
337f0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20   invoked.**     
33800 20 20 20 20 20 69 6e 20 61 6e 20 61 74 74 65 6d       in an attem
33810 70 74 20 74 6f 20 72 65 64 75 63 65 20 74 68 65  pt to reduce the
33820 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 70 72   memory usage pr
33830 69 6f 72 20 74 6f 20 70 72 6f 63 65 65 64 69 6e  ior to proceedin
33840 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  g.**          wi
33850 74 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  th the memory al
33860 6c 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74  location attempt
33870 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d  ..**.** {F16353}
33880 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   Calls to [sqlit
33890 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
338a0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
338b0 28 29 5d 20 74 68 61 74 20 74 72 69 67 67 65 72  ()] that trigger
338c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 74  .**          att
338d0 65 6d 70 74 73 20 74 6f 20 72 65 64 75 63 65 20  empts to reduce 
338e0 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 74 68 72  memory usage thr
338f0 6f 75 67 68 20 74 68 65 20 73 6f 66 74 20 68 65  ough the soft he
33900 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20  ap limit.**     
33910 20 20 20 20 20 6d 65 63 68 61 6e 69 73 6d 20 63       mechanism c
33920 6f 6e 74 69 6e 75 65 20 65 76 65 6e 20 69 66 20  ontinue even if 
33930 74 68 65 20 61 74 74 65 6d 70 74 20 74 6f 20 72  the attempt to r
33940 65 64 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  educe memory.** 
33950 20 20 20 20 20 20 20 20 20 75 73 61 67 65 20 69           usage i
33960 73 20 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a  s unsuccessful..
33970 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 20 41  **.** {F16354} A
33980 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
33990 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e  o value for N in
339a0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20   a call to.**   
339b0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
339c0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
339d0 4e 29 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  N)] means that t
339e0 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a  here is no soft.
339f0 2a 2a 20 20 20 20 20 20 20 20 20 20 68 65 61 70  **          heap
33a00 20 6c 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69   limit and [sqli
33a10 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
33a20 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20  ry()] will only 
33a30 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  be.**          c
33a40 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72  alled when memor
33a50 79 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20  y is completely 
33a60 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a  exhausted..**.**
33a70 20 7b 46 31 36 33 35 35 7d 20 54 68 65 20 64 65   {F16355} The de
33a80 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20  fault value for 
33a90 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
33aa0 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  mit is zero..**.
33ab0 2a 2a 20 7b 46 31 36 33 35 38 7d 20 45 61 63 68  ** {F16358} Each
33ac0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33ad0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
33ae0 74 28 4e 29 5d 20 6f 76 65 72 72 69 64 65 73 20  t(N)] overrides 
33af0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
33b00 76 61 6c 75 65 73 20 73 65 74 20 62 79 20 61 6c  values set by al
33b10 6c 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a  l prior calls..*
33b20 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
33b30 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
33b40 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
33b50 33 52 45 46 3a 20 20 45 78 74 72 61 63 74 20 4d  3REF:  Extract M
33b60 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
33b70 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
33b80 65 20 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a  e {F12850}.**.**
33b90 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   This routine.**
33ba0 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61   returns meta-da
33bb0 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
33bc0 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
33bd0 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61 73  specific databas
33be0 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73  e.** table acces
33bf0 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
33c00 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  connection handl
33c10 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
33c20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a  first function .
33c30 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ** argument..**.
33c40 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  ** The column is
33c50 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
33c60 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
33c70 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
33c80 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68  meters to .** th
33c90 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  is function. The
33ca0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
33cb0 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
33cc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
33cd0 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
33ce0 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20  ain", "temp" or 
33cf0 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
33d00 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
33d10 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
33d20 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
33d30 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
33d40 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
33d50 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
33d60 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
33d70 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
33d80 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
33d90 68 6d 20 61 73 20 74 68 65 20 64 61 74 61 62 61  hm as the databa
33da0 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74  se engine uses t
33db0 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  o .** resolve un
33dc0 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
33dd0 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
33de0 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20  * The third and 
33df0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
33e00 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
33e10 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
33e20 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20   and column .** 
33e30 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
33e40 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
33e50 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
33e60 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
33e70 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65  eters .** may be
33e80 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74   NULL..**.** Met
33e90 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  a information is
33ea0 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69   returned by wri
33eb0 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f  ting to the memo
33ec0 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73  ry locations pas
33ed0 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74  sed as.** the 5t
33ee0 68 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  h and subsequent
33ef0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
33f00 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e  his function. An
33f10 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61  y of these .** a
33f20 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20  rguments may be 
33f30 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63  NULL, in which c
33f40 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ase the correspo
33f50 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66  nding element of
33f60 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d   meta .** inform
33f70 61 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ation is omitted
33f80 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  ..**.** <pre>.**
33f90 20 50 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f   Parameter     O
33fa0 75 74 70 75 74 20 54 79 70 65 20 20 20 20 20 20  utput Type      
33fb0 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d  Description.** -
33fc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
33fd0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
33fe0 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20  --.**.**   5th  
33ff0 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61         const cha
34000 72 2a 20 20 20 20 20 20 44 61 74 61 20 74 79 70  r*      Data typ
34010 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20  e.**   6th      
34020 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20     const char*  
34030 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20      Name of the 
34040 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f  default collatio
34050 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20  n sequence .**  
34060 20 37 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   7th         int
34070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
34080 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
34090 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
340a0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20  constraint.**   
340b0 38 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  8th         int 
340c0 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
340d0 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
340e0 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
340f0 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20  RIMARY KEY.**   
34100 39 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  9th         int 
34110 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
34120 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
34130 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54  is AUTOINCREMENT
34140 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
34150 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70  .** The memory p
34160 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
34170 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
34180 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
34190 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61   the .** declara
341a0 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
341b0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
341c0 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
341d0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a  ntil the next .*
341e0 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71  * call to any sq
341f0 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f  lite API functio
34200 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
34210 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
34220 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
34230 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f  ew, then an erro
34240 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
34250 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
34260 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
34270 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
34280 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
34290 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50  an .** INTEGER P
342a0 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d  RIMARY KEY colum
342b0 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
342c0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
342d0 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20  then the output 
342e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
342f0 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
34300 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
34310 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68  ed column. If th
34320 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
34330 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
34340 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65   IPK column, the
34350 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70 61 72  n the output par
34360 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
34370 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a  as .** follows:.
34380 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
34390 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
343a0 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
343b0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
343c0 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
343d0 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
343e0 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
343f0 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
34400 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
34410 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68   </pre>.**.** Th
34420 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
34430 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
34440 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
34450 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
34460 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
34470 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
34480 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
34490 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
344a0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
344b0 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
344c0 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72   an SQLITE error
344d0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
344e0 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
344f0 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69  essage.** left i
34500 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  n the database h
34510 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74  andle (to be ret
34520 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
34530 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a  ite3_errmsg())..
34540 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69  **.** This API i
34550 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
34560 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
34570 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
34580 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
34590 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
345a0 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73  TADATA preproces
345b0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
345c0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
345d0 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
345e0 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
345f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
34600 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
34610 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
34620 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
34630 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
34640 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
34650 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
34660 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
34670 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
34680 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
34690 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
346a0 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
346b0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
346c0 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
346d0 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
346e0 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
346f0 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
34700 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
34710 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
34720 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
34730 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
34740 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
34750 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
34760 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
34770 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
34780 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
34790 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
347a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
347b0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
347c0 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
347d0 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
347e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
347f0 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
34800 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f  f column is auto
34810 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
34820 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34830 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
34840 69 6f 6e 20 7b 46 31 32 36 30 30 7d 0a 2a 2a 0a  ion {F12600}.**.
34850 2a 2a 20 7b 46 31 32 36 30 31 7d 20 54 68 65 20  ** {F12601} The 
34860 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
34870 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61  ension() interfa
34880 63 65 0a 2a 2a 20 61 74 74 65 6d 70 74 73 20 74  ce.** attempts t
34890 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65  o load an SQLite
348a0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
348b0 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20  ry contained in 
348c0 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c  the file.** zFil
348d0 65 2e 20 7b 46 31 32 36 30 32 7d 20 54 68 65 20  e. {F12602} The 
348e0 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a  entry point is z
348f0 50 72 6f 63 2e 20 7b 46 31 32 36 30 33 7d 20 7a  Proc. {F12603} z
34900 50 72 6f 63 20 6d 61 79 20 62 65 20 30 0a 2a 2a  Proc may be 0.**
34910 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
34920 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65  he name of the e
34930 6e 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75  ntry point defau
34940 6c 74 73 0a 2a 2a 20 74 6f 20 22 73 71 6c 69 74  lts.** to "sqlit
34950 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69  e3_extension_ini
34960 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30  t"..**.** {F1260
34970 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  4} The sqlite3_l
34980 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
34990 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 0a  interface shall.
349a0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
349b0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
349c0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52   and [SQLITE_ERR
349d0 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67  OR] if something
349e0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a   goes wrong..**.
349f0 2a 2a 20 7b 46 31 32 36 30 35 7d 0a 2a 2a 20 49  ** {F12605}.** I
34a00 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
34a10 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69  s and pzErrMsg i
34a20 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68  s not 0, then th
34a30 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 6f 61  e.** sqlite3_loa
34a40 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
34a50 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
34a60 74 65 6d 70 74 20 74 6f 20 66 69 6c 6c 20 2a 70  tempt to fill *p
34a70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a  zErrMsg with .**
34a80 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
34a90 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
34aa0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
34ab0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
34ac0 6f 63 28 29 5d 2e 0a 2a 2a 20 7b 45 4e 44 7d 20  oc()]..** {END} 
34ad0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
34ae0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65  ction should fre
34af0 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a  e this memory.**
34b00 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
34b10 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
34b20 0a 2a 2a 20 7b 46 31 32 36 30 36 7d 0a 2a 2a 20  .** {F12606}.** 
34b30 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
34b40 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65  g must be enable
34b50 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
34b60 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
34b70 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69  ension()].** pri
34b80 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68  or to calling th
34b90 69 73 20 41 50 49 20 6f 72 20 61 6e 20 65 72 72  is API or an err
34ba0 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  or will be retur
34bb0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
34bc0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
34bd0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
34be0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c  b,          /* L
34bf0 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f  oad the extensio
34c00 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61  n into this data
34c10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34c20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
34c30 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61  *zFile,    /* Na
34c40 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64  me of the shared
34c50 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
34c60 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f  ing extension */
34c70 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34c80 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72  Proc,    /* Entr
34c90 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65  y point.  Derive
34ca0 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20  d from zFile if 
34cb0 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  0 */.  char **pz
34cc0 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20  ErrMsg       /* 
34cd0 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67  Put error messag
34ce0 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20  e here if not 0 
34cf0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
34d00 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f  I3REF:  Enable O
34d10 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73  r Disable Extens
34d20 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32  ion Loading {F12
34d30 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73  620}.**.** So as
34d40 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
34d50 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
34d60 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
34d70 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
34d80 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
34d90 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
34da0 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
34db0 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
34dc0 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
34dd0 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
34de0 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
34df0 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
34e00 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50   following.** AP
34e10 49 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  I is provided to
34e20 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
34e30 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
34e40 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
34e50 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 7b  n and.** off.  {
34e60 46 31 32 36 32 32 7d 20 49 74 20 69 73 20 6f 66  F12622} It is of
34e70 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 7b 45  f by default. {E
34e80 4e 44 7d 20 53 65 65 20 74 69 63 6b 65 74 20 23  ND} See ticket #
34e90 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  1863..**.** {F12
34ea0 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71  621} Call the sq
34eb0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
34ec0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f  d_extension() ro
34ed0 75 74 69 6e 65 0a 2a 2a 20 77 69 74 68 20 6f 6e  utine.** with on
34ee0 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20 65  off==1 to turn e
34ef0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
34f00 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c 20   on.** and call 
34f10 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30  it with onoff==0
34f20 20 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63 6b   to turn it back
34f30 20 6f 66 66 20 61 67 61 69 6e 2e 20 7b 45 4e 44   off again. {END
34f40 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  }.*/.int sqlite3
34f50 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
34f60 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
34f70 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
34f80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34f90 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e   Make Arrangemen
34fa0 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61  ts To Automatica
34fb0 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  lly Load An Exte
34fc0 6e 73 69 6f 6e 20 7b 46 31 32 36 34 30 7d 0a 2a  nsion {F12640}.*
34fd0 2a 0a 2a 2a 20 7b 46 31 32 36 34 31 7d 20 54 68  *.** {F12641} Th
34fe0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  is function.** r
34ff0 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65  egisters an exte
35000 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e  nsion entry poin
35010 74 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61  t that is automa
35020 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a  tically invoked.
35030 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ** whenever a ne
35040 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
35050 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20  ction is opened 
35060 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
35070 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
35080 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
35090 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
350a0 76 32 28 29 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  v2()]. {END}.**.
350b0 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e 20  ** This API can 
350c0 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72  be invoked at pr
350d0 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e  ogram startup in
350e0 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74   order to regist
350f0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
35100 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e  e statically lin
35110 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74  ked extensions t
35120 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69  hat will be avai
35130 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20  lable.** to all 
35140 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
35150 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nections..**.** 
35160 7b 46 31 32 36 34 32 7d 20 44 75 70 6c 69 63 61  {F12642} Duplica
35170 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72  te extensions ar
35180 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61  e detected so ca
35190 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
351a0 6e 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  ne multiple.** t
351b0 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
351c0 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20  me extension is 
351d0 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  harmless..**.** 
351e0 7b 46 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f  {F12643} This ro
351f0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70  utine stores a p
35200 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78  ointer to the ex
35210 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72  tension in an ar
35220 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f  ray.** that is o
35230 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
35240 69 74 65 5f 6d 61 6c 6c 6f 63 28 29 2e 20 7b 45  ite_malloc(). {E
35250 4e 44 7d 20 49 66 20 79 6f 75 20 72 75 6e 20 61  ND} If you run a
35260 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20   memory leak.** 
35270 63 68 65 63 6b 65 72 20 6f 6e 20 79 6f 75 72 20  checker on your 
35280 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72  program and it r
35290 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65  eports a leak be
352a0 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a  cause of this.**
352b0 20 61 72 72 61 79 2c 20 74 68 65 6e 20 69 6e 76   array, then inv
352c0 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  oke [sqlite3_res
352d0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
352e0 6e 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f  n()] prior.** to
352f0 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65   shutdown to fre
35300 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  e the memory..**
35310 0a 2a 2a 20 7b 46 31 32 36 34 34 7d 20 41 75 74  .** {F12644} Aut
35320 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
35330 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61  s apply across a
35340 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44  ll threads. {END
35350 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
35360 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69  erface is experi
35370 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
35380 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
35390 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e  or.** removal in
353a0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
353b0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
353c0 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  nt sqlite3_auto_
353d0 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a  extension(void *
353e0 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a  xEntryPoint);...
353f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35400 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20  Reset Automatic 
35410 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
35420 67 20 7b 46 31 32 36 36 30 7d 0a 2a 2a 0a 2a 2a  g {F12660}.**.**
35430 20 7b 46 31 32 36 36 31 7d 20 54 68 69 73 20 66   {F12661} This f
35440 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
35450 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20   all previously 
35460 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 61 75  registered.** au
35470 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
35480 6e 73 2e 20 7b 45 4e 44 7d 20 20 54 68 69 73 0a  ns. {END}  This.
35490 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
354a0 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
354b0 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69 74  all prior [sqlit
354c0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
354d0 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a  n()].** calls..*
354e0 2a 0a 2a 2a 20 7b 46 31 32 36 36 32 7d 20 54 68  *.** {F12662} Th
354f0 69 73 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64  is call disabled
35500 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e   automatic exten
35510 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72  sions in all thr
35520 65 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  eads. {END}.**.*
35530 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
35540 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
35550 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20   and is subject 
35560 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  to change or.** 
35570 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
35580 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
35590 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  Lite..*/.void sq
355a0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
355b0 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29  _extension(void)
355c0 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58  ;.../*.****** EX
355d0 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62  PERIMENTAL - sub
355e0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77  ject to change w
355f0 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a  ithout notice **
35600 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
35610 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
35620 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
35630 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
35640 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
35650 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
35660 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
35670 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
35680 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
35690 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
356a0 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
356b0 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
356c0 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
356d0 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
356e0 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
356f0 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
35700 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
35710 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77  stabilizes, we w
35720 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a  ill declare the.
35730 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78  ** interface fix
35740 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69  ed, support it i
35750 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64  ndefinitely, and
35760 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d   remove this com
35770 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  ment..*/../*.** 
35780 53 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20  Structures used 
35790 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  by the virtual t
357a0 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  able interface.*
357b0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
357c0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71   sqlite3_vtab sq
357d0 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65  lite3_vtab;.type
357e0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
357f0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71  e3_index_info sq
35800 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
35810 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
35820 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
35830 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61  rsor sqlite3_vta
35840 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65  b_cursor;.typede
35850 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
35860 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f  _module sqlite3_
35870 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  module;../*.** C
35880 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
35890 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b 46   Table Object {F
358a0 31 38 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  18000}.** KEYWOR
358b0 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  DS: sqlite3_modu
358c0 6c 65 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c  le.**.** A modul
358d0 65 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20  e is a class of 
358e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20  virtual tables. 
358f0 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20   Each module is 
35900 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e  defined.** by an
35910 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
35920 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
35930 74 75 72 65 2e 20 20 54 68 69 73 20 73 74 72 75  ture.  This stru
35940 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a  cture consists.*
35950 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68  * mostly of meth
35960 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
35970 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  le..*/.struct sq
35980 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20  lite3_module {. 
35990 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
359a0 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28   int (*xCreate)(
359b0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
359c0 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
359d0 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
359e0 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
359f0 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
35a00 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
35a10 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
35a20 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  r**);.  int (*xC
35a30 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a  onnect)(sqlite3*
35a40 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
35a50 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
35a60 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
35a70 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
35a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
35a90 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
35aa0 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
35ab0 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78  int (*xBestIndex
35ac0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
35ad0 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69  pVTab, sqlite3_i
35ae0 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69  ndex_info*);.  i
35af0 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74  nt (*xDisconnect
35b00 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
35b10 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
35b20 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65  xDestroy)(sqlite
35b30 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
35b40 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
35b50 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
35b60 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62  ab, sqlite3_vtab
35b70 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73  _cursor **ppCurs
35b80 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  or);.  int (*xCl
35b90 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ose)(sqlite3_vta
35ba0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
35bb0 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c  t (*xFilter)(sql
35bc0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
35bd0 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63  *, int idxNum, c
35be0 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74  onst char *idxSt
35bf0 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  r,.             
35c00 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c     int argc, sql
35c10 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67  ite3_value **arg
35c20 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78  v);.  int (*xNex
35c30 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  t)(sqlite3_vtab_
35c40 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
35c50 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f  (*xEof)(sqlite3_
35c60 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
35c70 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28   int (*xColumn)(
35c80 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
35c90 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f  sor*, sqlite3_co
35ca0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20  ntext*, int);.  
35cb0 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71  int (*xRowid)(sq
35cc0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
35cd0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
35ce0 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e  4 *pRowid);.  in
35cf0 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c  t (*xUpdate)(sql
35d00 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74  ite3_vtab *, int
35d10 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  , sqlite3_value 
35d20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  **, sqlite3_int6
35d30 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  4 *);.  int (*xB
35d40 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  egin)(sqlite3_vt
35d50 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
35d60 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
35d70 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
35d80 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74  .  int (*xCommit
35d90 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
35da0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
35db0 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74  xRollback)(sqlit
35dc0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
35dd0 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75  .  int (*xFindFu
35de0 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f  nction)(sqlite3_
35df0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74  vtab *pVtab, int
35e00 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61   nArg, const cha
35e10 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20  r *zName,.      
35e20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35e30 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29   void (**pxFunc)
35e40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35e50 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
35e60 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20  lue**),.        
35e70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
35e80 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20  oid **ppArg);.. 
35e90 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28   int (*xRename)(
35ea0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
35eb0 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  tab, const char 
35ec0 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  *zNew);.};../*.*
35ed0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
35ee0 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69  ual Table Indexi
35ef0 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b  ng Information {
35f00 46 31 38 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F18100}.** KEYWO
35f10 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64  RDS: sqlite3_ind
35f20 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68  ex_info.**.** Th
35f30 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  e sqlite3_index_
35f40 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61  info structure a
35f50 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74  nd its substruct
35f60 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a  ures is used to.
35f70 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74  ** pass informat
35f80 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63  ion into and rec
35f90 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66  eive the reply f
35fa0 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64  rom the xBestInd
35fb0 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ex.** method of 
35fc0 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  an sqlite3_modul
35fd0 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75  e.  The fields u
35fe0 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20  nder **Inputs** 
35ff0 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  are the.** input
36000 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20  s to xBestIndex 
36010 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c  and are read-onl
36020 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69  y.  xBestIndex i
36030 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65  nserts its.** re
36040 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a  sults into the *
36050 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64  *Outputs** field
36060 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f  s..**.** The aCo
36070 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
36080 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63   records WHERE c
36090 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
360a0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
360b0 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20  :.**.**         
360c0 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a  column OP expr.*
360d0 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73  *.** Where OP is
360e0 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c   =, &lt;, &lt;=,
360f0 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e   &gt;, or &gt;=.
36100 20 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63    .** The partic
36110 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73  ular operator is
36120 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43   stored.** in aC
36130 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20  onstraint[].op. 
36140 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   The index of th
36150 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72  e column is stor
36160 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74  ed in .** aConst
36170 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e  raint[].iColumn.
36180 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e    aConstraint[].
36190 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69  usable is TRUE i
361a0 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e  f the.** expr on
361b0 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
361c0 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c  side can be eval
361d0 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20  uated (and thus 
361e0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  the constraint.*
361f0 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64  * is usable) and
36200 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e   false if it can
36210 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  not..**.** The o
36220 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74  ptimizer automat
36230 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74  ically inverts t
36240 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  erms of the form
36250 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e   "expr OP column
36260 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f  ".** and makes o
36270 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74  ther simplificat
36280 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52  ions to the WHER
36290 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61  E clause in an a
362a0 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74  ttempt to.** get
362b0 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63   as many WHERE c
362c0 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f  lause terms into
362d0 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20   the form shown 
362e0 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c  above as possibl
362f0 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74  e..** The aConst
36300 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e  raint[] array on
36310 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45  ly reports WHERE
36320 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e   clause terms in
36330 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20   the correct.** 
36340 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20  form that refer 
36350 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
36360 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
36370 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
36380 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e  *.** Information
36390 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52   about the ORDER
363a0 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74   BY clause is st
363b0 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79  ored in aOrderBy
363c0 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d  []..** Each term
363d0 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63   of aOrderBy rec
363e0 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66  ords a column of
363f0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
36400 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ause..**.** The 
36410 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f  xBestIndex metho
36420 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e  d must fill aCon
36430 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77  straintUsage[] w
36440 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ith information.
36450 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61  ** about what pa
36460 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73  rameters to pass
36470 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66   to xFilter.  If
36480 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65   argvIndex>0 the
36490 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68  n.** the right-h
364a0 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20  and side of the 
364b0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43  corresponding aC
364c0 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65  onstraint[] is e
364d0 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20  valuated.** and 
364e0 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76  becomes the argv
364f0 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69  Index-th entry i
36500 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e  n argv.  If aCon
36510 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f  straintUsage[].o
36520 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20  mit.** is true, 
36530 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61  then the constra
36540 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74  int is assumed t
36550 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c  o be fully handl
36560 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72  ed by the.** vir
36570 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69  tual table and i
36580 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67  s not checked ag
36590 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ain by SQLite..*
365a0 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20  *.** The idxNum 
365b0 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65  and idxPtr value
365c0 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61  s are recorded a
365d0 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78  nd passed into x
365e0 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74  Filter..** sqlit
365f0 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 65  e3_free() is use
36600 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72  d to free idxPtr
36610 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64   if needToFreeId
36620 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a  xPtr is true..**
36630 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43  .** The orderByC
36640 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68  onsumed means th
36650 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78  at output from x
36660 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75  Filter will occu
36670 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72  r in.** the corr
36680 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74  ect order to sat
36690 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42  isfy the ORDER B
366a0 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74  Y clause so that
366b0 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20   no separate.** 
366c0 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20  sorting step is 
366d0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
366e0 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  The estimatedCos
366f0 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73  t value is an es
36700 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f  timate of the co
36710 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a  st of doing the.
36720 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f  ** particular lo
36730 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63  okup.  A full sc
36740 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69  an of a table wi
36750 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f  th N entries sho
36760 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f  uld have.** a co
36770 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61  st of N.  A bina
36780 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74  ry search of a t
36790 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65  able of N entrie
367a0 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a  s should have a.
367b0 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f  ** cost of appro
367c0 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e  ximately log(N).
367d0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
367e0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a  e3_index_info {.
367f0 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20    /* Inputs */. 
36800 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74   int nConstraint
36810 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ;           /* N
36820 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73  umber of entries
36830 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20   in aConstraint 
36840 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
36850 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72  te3_index_constr
36860 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20  aint {.     int 
36870 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20  iColumn;        
36880 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20        /* Column 
36890 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  on left-hand sid
368a0 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20  e of constraint 
368b0 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
368c0 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20   char op;       
368d0 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20    /* Constraint 
368e0 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20  operator */.    
368f0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75   unsigned char u
36900 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72  sable;     /* Tr
36910 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74  ue if this const
36920 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20  raint is usable 
36930 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72  */.     int iTer
36940 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20  mOffset;        
36950 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e    /* Used intern
36960 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65  ally - xBestInde
36970 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20  x should ignore 
36980 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61  */.  } *aConstra
36990 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20  int;            
369a0 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52  /* Table of WHER
369b0 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
369c0 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f  ints */.  int nO
369d0 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
369e0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
369f0 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f  f terms in the O
36a00 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
36a10 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
36a20 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79  e3_index_orderby
36a30 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
36a40 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
36a50 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62    /* Column numb
36a60 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  er */.     unsig
36a70 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20  ned char desc;  
36a80 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72       /* True for
36a90 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f   DESC.  False fo
36aa0 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61  r ASC. */.  } *a
36ab0 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
36ac0 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52         /* The OR
36ad0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
36ae0 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a  ..  /* Outputs *
36af0 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
36b00 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
36b10 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20  int_usage {.    
36b20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20  int argvIndex;  
36b30 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e           /* if >
36b40 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  0, constraint is
36b50 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f   part of argv to
36b60 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20   xFilter */.    
36b70 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d  unsigned char om
36b80 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e  it;      /* Do n
36b90 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66  ot code a test f
36ba0 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  or this constrai
36bb0 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73  nt */.  } *aCons
36bc0 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69  traintUsage;.  i
36bd0 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20  nt idxNum;      
36be0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
36bf0 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e  ber used to iden
36c00 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a  tify the index *
36c10 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72  /.  char *idxStr
36c20 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
36c30 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62  * String, possib
36c40 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
36c50 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20   sqlite3_malloc 
36c60 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46  */.  int needToF
36c70 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20  reeIdxStr;      
36c80 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75  /* Free idxStr u
36c90 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  sing sqlite3_fre
36ca0 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20  e() if true */. 
36cb0 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73   int orderByCons
36cc0 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54  umed;       /* T
36cd0 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73  rue if output is
36ce0 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64   already ordered
36cf0 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74   */.  double est
36d00 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20  imatedCost;     
36d10 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f   /* Estimated co
36d20 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  st of using this
36d30 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65   index */.};.#de
36d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
36d50 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20  X_CONSTRAINT_EQ 
36d60 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
36d70 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
36d80 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65  AINT_GT    4.#de
36d90 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
36da0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20  X_CONSTRAINT_LE 
36db0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
36dc0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
36dd0 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64  AINT_LT    16.#d
36de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
36df0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45  EX_CONSTRAINT_GE
36e00 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
36e10 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
36e20 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a  TRAINT_MATCH 64.
36e30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36e40 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74   Register A Virt
36e50 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d  ual Table Implem
36e60 65 6e 74 61 74 69 6f 6e 20 7b 46 31 38 32 30 30  entation {F18200
36e70 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
36e80 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20  tine is used to 
36e90 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d  register a new m
36ea0 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20  odule name with 
36eb0 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e  an SQLite.** con
36ec0 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65  nection.  Module
36ed0 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72   names must be r
36ee0 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65  egistered before
36ef0 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a   creating new.**
36f00 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
36f10 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f  on the module, o
36f20 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70  r before using p
36f30 72 65 65 78 69 73 74 69 6e 67 20 76 69 72 74 75  reexisting virtu
36f40 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20  al.** tables of 
36f50 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69  the module..*/.i
36f60 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36f70 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69  e_module(.  sqli
36f80 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
36f90 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
36fa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
36fb0 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
36fc0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
36fd0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
36fe0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
36ff0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
37000 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
37010 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74  ule *,    /* Met
37020 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
37030 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20  ule */.  void * 
37040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37050 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
37060 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
37070 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f  Connect */.);../
37080 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
37090 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61  egister A Virtua
370a0 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e  l Table Implemen
370b0 74 61 74 69 6f 6e 20 7b 46 31 38 32 31 30 7d 0a  tation {F18210}.
370c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
370d0 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  ne is identical 
370e0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  to the sqlite3_c
370f0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d  reate_module() m
37100 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20  ethod above,.** 
37110 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
37120 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74  llows a destruct
37130 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  or function to b
37140 65 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20  e specified. It 
37150 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20  is.** even more 
37160 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61  experimental tha
37170 6e 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68  n the rest of th
37180 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  e virtual tables
37190 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   API..*/.int sql
371a0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
371b0 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  le_v2(.  sqlite3
371c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
371d0 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
371e0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
371f0 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
37200 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
37210 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
37220 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
37230 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
37240 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
37250 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *,    /* Method
37260 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
37270 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
37280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37290 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
372a0 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
372b0 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a  nect */.  void(*
372c0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
372d0 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64       /* Module d
372e0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
372f0 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  on */.);../*.** 
37300 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
37310 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65  l Table Instance
37320 20 4f 62 6a 65 63 74 20 7b 46 31 38 30 31 30 7d   Object {F18010}
37330 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
37340 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a  lite3_vtab.**.**
37350 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d   Every module im
37360 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
37370 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  s a subclass of 
37380 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
37390 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65  ructure.** to de
373a0 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75  scribe a particu
373b0 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  lar instance of 
373c0 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63  the module.  Eac
373d0 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a  h subclass will.
373e0 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74  ** be tailored t
373f0 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
37400 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  eeds of the modu
37410 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
37420 6e 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70  n.   The.** purp
37430 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65  ose of this supe
37440 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66  rclass is to def
37450 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c  ine certain fiel
37460 64 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d  ds that are comm
37470 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64  on.** to all mod
37480 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
37490 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75  ons..**.** Virtu
374a0 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64  al tables method
374b0 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72  s can set an err
374c0 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73  or message by as
374d0 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72  signing a.** str
374e0 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
374f0 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
37500 66 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  f() to zErrMsg. 
37510 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
37520 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
37530 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
37540 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
37550 79 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  y a call to sqli
37560 74 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72  te3_free().** pr
37570 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67  ior to assigning
37580 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f   a new string to
37590 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72   zErrMsg.  After
375a0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
375b0 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72  ge.** is deliver
375c0 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69  ed up to the cli
375d0 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ent application,
375e0 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
375f0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
37600 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71  y.** freed by sq
37610 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64  lite3_free() and
37620 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
37630 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65  ld will be zeroe
37640 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74  d.  Note.** that
37650 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
37660 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66  () and sqlite3_f
37670 72 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f  ree() are used o
37680 6e 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69  n the zErrMsg fi
37690 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72  eld.** since vir
376a0 74 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20  tual tables are 
376b0 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65  commonly impleme
376c0 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65  nted in loadable
376d0 20 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63   extensions whic
376e0 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65  h.** do not have
376f0 20 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74   access to sqlit
37700 65 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73  e3MPrintf() or s
37710 71 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f  qlite3Free()..*/
37720 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
37730 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73  vtab {.  const s
37740 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
37750 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20  Module;  /* The 
37760 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20  module for this 
37770 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f  virtual table */
37780 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20  .  int nRef;    
37790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
377a0 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72     /* Used inter
377b0 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20  nally */.  char 
377c0 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20  *zErrMsg;       
377d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
377e0 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d  ror message from
377f0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
37800 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  () */.  /* Virtu
37810 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
37820 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
37830 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
37840 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
37850 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
37860 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
37870 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74  le Cursor Object
37880 20 20 7b 46 31 38 30 32 30 7d 0a 2a 2a 20 4b 45    {F18020}.** KE
37890 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
378a0 76 74 61 62 5f 63 75 72 73 6f 72 0a 2a 2a 0a 2a  vtab_cursor.**.*
378b0 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69  * Every module i
378c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73  mplementation us
378d0 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  es a subclass of
378e0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
378f0 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64  tructure.** to d
37900 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20  escribe cursors 
37910 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20  that point into 
37920 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
37930 65 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a  e and are used.*
37940 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67  * to loop throug
37950 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  h the virtual ta
37960 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72  ble.  Cursors ar
37970 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
37980 74 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 74  the.** xOpen met
37990 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  hod of the modul
379a0 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  e.  Each module 
379b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
379c0 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68  ill define.** th
379d0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63  e content of a c
379e0 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20  ursor structure 
379f0 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20  to suit its own 
37a00 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  needs..**.** Thi
37a10 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69  s superclass exi
37a20 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  sts in order to 
37a30 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66  define fields of
37a40 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74   the cursor that
37a50 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74  .** are common t
37a60 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61  o all implementa
37a70 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74  tions..*/.struct
37a80 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
37a90 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33  rsor {.  sqlite3
37aa0 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20  _vtab *pVtab;   
37ab0 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61     /* Virtual ta
37ac0 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73  ble of this curs
37ad0 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  or */.  /* Virtu
37ae0 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
37af0 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
37b00 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
37b10 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
37b20 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
37b30 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65  REF: Declare The
37b40 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72   Schema Of A Vir
37b50 74 75 61 6c 20 54 61 62 6c 65 20 7b 46 31 38 32  tual Table {F182
37b60 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43  80}.**.** The xC
37b70 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65  reate and xConne
37b80 63 74 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20  ct methods of a 
37b90 6d 6f 64 75 6c 65 20 75 73 65 20 74 68 65 20 66  module use the f
37ba0 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20  ollowing API.** 
37bb0 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66  to declare the f
37bc0 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73  ormat (the names
37bd0 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f   and datatypes o
37be0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f  f the columns) o
37bf0 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c  f.** the virtual
37c00 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70   tables they imp
37c10 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73  lement..*/.int s
37c20 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
37c30 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  tab(sqlite3*, co
37c40 6e 73 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74  nst char *zCreat
37c50 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  eTable);../*.** 
37c60 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f  CAPI3REF: Overlo
37c70 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f  ad A Function Fo
37c80 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
37c90 65 20 7b 46 31 38 33 30 30 7d 0a 2a 2a 0a 2a 2a  e {F18300}.**.**
37ca0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
37cb0 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65  can provide alte
37cc0 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e  rnative implemen
37cd0 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74  tations of funct
37ce0 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ions.** using th
37cf0 65 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 20  e xFindFunction 
37d00 6d 65 74 68 6f 64 2e 20 20 42 75 74 20 67 6c 6f  method.  But glo
37d10 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  bal versions of 
37d20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a  those functions.
37d30 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e  ** must exist in
37d40 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65   order to be ove
37d50 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  rloaded..**.** T
37d60 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75  his API makes su
37d70 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73  re a global vers
37d80 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f  ion of a functio
37d90 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  n with a particu
37da0 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20  lar.** name and 
37db0 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
37dc0 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66  ters exists.  If
37dd0 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f   no such functio
37de0 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f  n exists.** befo
37df0 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63  re this API is c
37e00 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e  alled, a new fun
37e10 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
37e20 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
37e30 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20  ation.** of the 
37e40 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77  new function alw
37e50 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78  ays causes an ex
37e60 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  ception to be th
37e70 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65  rown.  So.** the
37e80 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73   new function is
37e90 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e   not good for an
37ea0 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66  ything by itself
37eb0 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70  .  Its only.** p
37ec0 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20  urpose is to be 
37ed0 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75  a placeholder fu
37ee0 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20  nction that can 
37ef0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a  be overloaded.**
37f00 20 62 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c   by virtual tabl
37f10 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  es..**.** This A
37f20 50 49 20 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e  PI should be con
37f30 73 69 64 65 72 65 64 20 70 61 72 74 20 6f 66 20  sidered part of 
37f40 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
37f50 65 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  e interface,.** 
37f60 77 68 69 63 68 20 69 73 20 65 78 70 65 72 69 6d  which is experim
37f70 65 6e 74 61 6c 20 61 6e 64 20 73 75 62 6a 65 63  ental and subjec
37f80 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  t to change..*/.
37f90 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72  int sqlite3_over
37fa0 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71  load_function(sq
37fb0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
37fc0 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69  ar *zFuncName, i
37fd0 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a  nt nArg);../*.**
37fe0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
37ff0 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
38000 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65  ble mechanism de
38010 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63  fined above (bac
38020 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d  k up.** to a com
38030 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20  ment remarkably 
38040 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20  similar to this 
38050 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c  one) is currentl
38060 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
38070 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
38080 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
38090 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
380a0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
380b0 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
380c0 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
380d0 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
380e0 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
380f0 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
38100 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
38110 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
38120 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
38130 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
38140 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
38150 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
38160 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
38170 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
38180 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  s comment..**.**
38190 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
381a0 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
381b0 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
381c0 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
381d0 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ***.*/../*.** CA
381e0 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65  PI3REF: A Handle
381f0 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   To An Open BLOB
38200 20 7b 46 31 37 38 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F17800}.**.** 
38210 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
38220 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
38230 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c  sents an open BL
38240 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 69  OB on which.** i
38250 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 63  ncremental I/O c
38260 61 6e 20 62 65 20 70 72 65 66 6f 72 6d 65 64 2e  an be preformed.
38270 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74  .** Objects of t
38280 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65  his type are cre
38290 61 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  ated by.** [sqli
382a0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
382b0 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62   and destroyed b
382c0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
382d0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  close()]..** The
382e0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
382f0 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
38300 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
38310 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
38320 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
38330 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
38340 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
38350 66 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54  f the blob..** T
38360 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
38370 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
38380 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
38390 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62  size of the.** b
383a0 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  lob in bytes..*/
383b0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
383c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
383d0 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
383e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
383f0 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
38400 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 46 31 37  emental I/O {F17
38410 38 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  810}.**.** This 
38420 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73  interfaces opens
38430 20 61 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65   a handle to the
38440 20 62 6c 6f 62 20 6c 6f 63 61 74 65 64 0a 2a 2a   blob located.**
38450 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f   in row iRow, co
38460 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61  lumn zColumn, ta
38470 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
38480 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69  tabase zDb;.** i
38490 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 20  n other words,  
384a0 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68  the same blob th
384b0 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65  at would be sele
384c0 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
384d0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
384e0 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
384f0 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
38500 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b 0a 2a   rowid = iRow;.*
38510 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a  * </pre> {END}.*
38520 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67  *.** If the flag
38530 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
38540 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f  on-zero, the blo
38550 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  b is opened for 
38560 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20 77 72 69  .** read and wri
38570 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74  te access. If it
38580 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c   is zero, the bl
38590 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  ob is opened for
385a0 20 72 65 61 64 20 0a 2a 2a 20 61 63 63 65 73 73   read .** access
385b0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
385c0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  t the database n
385d0 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66  ame is not the f
385e0 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e  ilename that con
385f0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  tains.** the dat
38600 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72  abase but rather
38610 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61   the symbolic na
38620 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
38630 73 65 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 73  se that.** is as
38640 73 69 67 6e 65 64 20 77 68 65 6e 20 74 68 65 20  signed when the 
38650 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e  database is conn
38660 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54  ected using [ATT
38670 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65  ACH]..** For the
38680 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
38690 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73  ile, the databas
386a0 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
386b0 2e 20 20 46 6f 72 0a 2a 2a 20 54 45 4d 50 20 74  .  For.** TEMP t
386c0 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62  ables, the datab
386d0 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d  ase name is "tem
386e0 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  p"..**.** On suc
386f0 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  cess, [SQLITE_OK
38700 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
38710 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73  d the new .** [s
38720 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
38730 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72  ob handle] is wr
38740 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62  itten to *ppBlob
38750 2e 20 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20  . .** Otherwise 
38760 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  an error code is
38770 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a   returned and .*
38780 2a 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74  * any value writ
38790 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73  ten to *ppBlob s
387a0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
387b0 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e  d by the caller.
387c0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
387d0 6e 20 73 65 74 73 20 74 68 65 20 64 61 74 61 62  n sets the datab
387e0 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f 72  ase-handle error
387f0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
38800 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
38810 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
38820 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
38830 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
38840 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  ** .** INVARIANT
38850 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 33  S:.**.** {F17813
38860 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
38870 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
38880 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
38890 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c 46 2c  pen(D,B,T,C,R,F,
388a0 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  P)].**          
388b0 69 6e 74 65 72 66 61 63 65 20 6f 70 65 6e 73 20  interface opens 
388c0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  an [sqlite3_blob
388d0 5d 20 6f 62 6a 65 63 74 20 50 20 6f 6e 20 74 68  ] object P on th
388e0 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20 20  e blob.**       
388f0 20 20 20 69 6e 20 63 6f 6c 75 6d 6e 20 43 20 6f     in column C o
38900 66 20 74 61 62 6c 65 20 54 20 69 6e 20 64 61 74  f table T in dat
38910 61 62 61 73 65 20 42 20 6f 6e 20 5b 64 61 74 61  abase B on [data
38920 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38930 20 44 2e 0a 2a 2a 0a 2a 2a 20 7